Skip to content

docs: add repository guidelines and documentation #31

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kumawatkaran523 merged 8 commits into from
Aug 12, 2026
Merged

docs: add repository guidelines and documentation #31

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e8373d8
docs: add MAINTAINERS.md
Atharva0506 Aug 10, 2026
3352a26
docs: add repository guidelines and documentation
Atharva0506 Aug 11, 2026
b8d0a7c
chore: update best practices score [skip ci]
github-actions[bot] Aug 11, 2026
9dcdea4
docs: address CodeRabbit review feedback
Atharva0506 Aug 11, 2026
6a5c0d3
chore: update best practices score [skip ci]
github-actions[bot] Aug 11, 2026
f4cb7bf
chore: untrack local relay-server binary, add to .gitignore
Atharva0506 Aug 11, 2026
1dc17ba
docs: remove unverified AOSSIE brand color attribution in Brand.md
Atharva0506 Aug 11, 2026
1f0ef93
fix: correct spelling of Karan's name in MAINTAINERS.md
Atharva0506 Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,4 @@ Thumbs.db

# Build / Release
dist/
relay

@coderabbitai coderabbitai Bot Aug 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
git check-ignore -v --no-index cmd/relay

Repository: AOSSIE-Org/ThruBox-Server

Length of output: 193

🏁 Script executed:

#!/bin/bash
set -euo pipefail
printf '%s\n' '--- .gitignore ---'
cat -n .gitignore
printf '%s\n' '--- AGENTS.md references ---'
rg -n -C 3 'cmd/relay|(^|[^[:alnum:]_])relay([^[:alnum:]_]|$)' AGENTS.md . 2>/dev/null | head -200
printf '%s\n' '--- tracked relay paths ---'
git ls-files | rg '(^|/)relay($|/)' || true
printf '%s\n' '--- ignore checks ---'
for path in relay cmd/relay cmd/relay/main.go; do
  printf '%s: ' "$path"
  git check-ignore -v --no-index "$path" || true
done
printf '%s\n' '--- repository status ---'
git status --short --untracked-files=all

Repository: AOSSIE-Org/ThruBox-Server

Length of output: 11804

Anchor the relay ignore rule to the repository root.

The current rule ignores cmd/relay and its files. Change it to /relay if it targets a root-level build artifact.

Proposed fix 
-relay
+/relay
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
relay
/relay
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.gitignore at line 34, Update the relay entry in .gitignore from an
unanchored pattern to /relay so only the repository-root build artifact is
ignored, while preserving nested cmd/relay files.

42 changes: 42 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# AGENTS.md

Instructions for AI coding agents working in this repository.

## Project Overview

ThruBox Server is a self-hostable relay server acting as a "dumb encrypted mailbox": it stores and forwards opaque encrypted payloads via a REST API. It never sees plaintext — all encryption/decryption happens client-side in the [ThruBox Client SDK](https://github.com/AOSSIE-Org/ThruBox-Client) or other consumers.

## Repository Layout

- `cmd/relay/` — server entrypoint
- Storage: embedded SQLite (WAL mode) via `mattn/go-sqlite3`
- `public/` — logo assets referenced by README
- `brand/` — logo, favicons, and brand guidelines (see `brand/Brand.md`)

## Build, Test & Lint

```bash
go mod download
go build -o relay-server ./cmd/relay
go vet ./...
go test ./...
./relay-server # run in a separate terminal — this blocks
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.

Docker:

```bash
Comment thread
coderabbitai[bot] marked this conversation as resolved.
docker compose up -d
```

**Note:** there are no `_test.go` files in the repository yet. If you add functionality, add tests alongside it — don't rely on this note as an excuse to skip tests.

## Hard Constraints

- Keep runtime dependencies minimal: standard library `net/http` plus `mattn/go-sqlite3`, `google/uuid`, and `yaml.v3` (see `go.mod`) — don't add a web framework, ORM, or other new dependency without discussing it in an issue first.
- All SQL must be parameterized (no string-concatenated queries) — this is a relay storing arbitrary payloads, so injection surface must stay closed.
- The server must never decrypt or inspect message payloads; it only stores/forwards opaque blobs.

## Conventions

- Configuration is read from `config.yaml` or environment variables (see the table in `README.md` "Configuration") — don't hardcode values that are already configurable.
182 changes: 88 additions & 94 deletions BestPracticesChecklist.md
View file
Open in desktop

Large diffs are not rendered by default.

42 changes: 24 additions & 18 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Contributing to TODO: Project Name
# Contributing to ThruBox Server

⭐ First off, thank you for considering contributing to this project! ⭐

Expand All @@ -9,7 +9,7 @@ We welcome contributions from everyone. By participating in this project, you ag
**All project communication MUST happen on Discord. We do not pay attention to GitHub notifications.**

- Join our [Discord server](https://discord.gg/hjUhu33uAn) before starting any work
- Post your PR/issue updates in the relevant Discord channel (**MANDATORY**)
- Post your PR/issue updates in the [#thrubox channel](https://discord.com/channels/995968619034984528/1525382676964446258) (**MANDATORY**)
- All discussions, questions, and updates should be on Discord
- GitHub is for code only - Discord is for communication

Expand Down Expand Up @@ -68,36 +68,42 @@ What we expect:

### Prerequisites

TODO: List prerequisites specific to your project
- Go 1.23+ with CGo enabled (required for SQLite)
- GCC (for compiling `go-sqlite3`)
- Docker (optional, for containerized deployment)

### Setup

1. **Fork the Repository**

```bash
# Click the 'Fork' button at the top right of this page
```

2. **Clone Your Fork**

```bash
git clone https://github.com/YOUR_USERNAME/TODO.git
cd TODO
git clone https://github.com/YOUR_USERNAME/ThruBox-Server.git
cd ThruBox-Server
```

3. **Add Upstream Remote**

```bash
git remote add upstream https://github.com/AOSSIE-Org/TODO.git
git remote add upstream https://github.com/AOSSIE-Org/ThruBox-Server.git
```

4. **Install Dependencies**

```bash
npm install
# or yarn install
# or pnpm install
go mod download
```

5. **Run the Project**

```bash
npm run dev
go build -o relay-server ./cmd/relay
./relay-server
```

## 🔄 Development Workflow
Expand All @@ -121,14 +127,14 @@ git checkout -b fix/your-bug-fix

### 3. Test Your Changes

TODO: Add project-specific testing instructions

```bash
npm test
# or
npm run lint
go build ./... # make sure it compiles
go vet ./... # static checks
go test ./... # run the test suite
```

The repository doesn't have test files yet — if you're adding new functionality, please add `_test.go` coverage for it alongside your change.

### 4. Commit Your Changes

Write clear, concise commit messages:
Expand Down Expand Up @@ -210,7 +216,7 @@ Steps to test the changes

### After Submission

- Post your PR in the project's Discord channel for visibility(**IMPORTANT**)
- Post your PR in the [#thrubox channel](https://discord.com/channels/995968619034984528/1525382676964446258) for visibility(**IMPORTANT**)
- Respond to review comments promptly
- Make requested changes in new commits
- Be patient - maintainers will review when available
Expand All @@ -223,7 +229,7 @@ Steps to test the changes

## 📝 Code Style Guidelines

TODO: Add project-specific code style guidelines
This is a Go project that keeps runtime dependencies minimal: `net/http` from the standard library plus `github.com/mattn/go-sqlite3`, `github.com/google/uuid`, and `gopkg.in/yaml.v3` (see `go.mod`). Discuss any new runtime dependency in an issue first. Run `gofmt`/`go vet` before committing, and keep the storage layer parameterized (no string-concatenated SQL) to avoid injection issues.

### General Guidelines

Expand Down Expand Up @@ -538,4 +544,4 @@ If you encounter issues not covered here:
- Check for existing PRs before starting to avoid duplication, as there might PRs that didn't mention the related issue


Thank you for contributing to TODO! Your efforts help make this project better for everyone. 🚀
Thank you for contributing to ThruBox Server! Your efforts help make this project better for everyone. 🚀
25 changes: 25 additions & 0 deletions MAINTAINERS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Maintainers, Mentors and Ideators

This document lists the individuals fulfilling the key roles of [Maintainer](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Maintainer.md), [Mentor](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Mentors.md) and [Ideator](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Ideator.md) for this repository, in accordance with [AOSSIE's Role Definitions](https://github.com/AOSSIE-Org/Info/tree/main/Roles).
Comment thread
Atharva0506 marked this conversation as resolved.

---

> **Note:** If multiple contributors are fulfilling a role in a single repository, please include and fill out the extra columns to clarify responsibilities (e.g., `Project / Feature Idea`, `Area / Focus`, and `Proposal / Discussion Link` for Ideators; `Area / Focus` for Mentors and Maintainers). If there is only one person for a role, do not add these columns.

## Mentors

| Name | GitHub Username | Discord Username |
| ----- | ---------------- | ------------------ |
| Bruno | @Zahnentferner | @b.wp |

## Maintainers

| Name | GitHub Username | Discord Username | Area / Focus |
| ------- | ------------------- | ------------------ | ----------------------------------- |
| Atharva | @Atharva0506 | @atharva0506 | Repository Maintenance & Merging |
| Karan | @kumawatkaran523 | @karankk9616 | Repository Maintenance & Merging |
| Aditya | @adityabhattad2021 | @adityabhattad | Repository Maintenance & Merging |
Comment thread
Atharva0506 marked this conversation as resolved.

## Ideators

_No Ideators are currently assigned to this repository._
11 changes: 9 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,14 @@ The server starts on `http://localhost:3000` with a SQLite database that auto-cr
docker compose up -d
```

#### 5. Run Tests

```bash
go test ./...
```

> No test files exist in the repository yet — this is the standard command to run once tests are added. See `CONTRIBUTING.md` before submitting a PR that adds functionality without tests.

### Configuration

Edit `config.yaml` or use environment variables:
Expand All @@ -208,8 +216,7 @@ Thank you for considering contributing to this project! Contributions are highly

## ✨ Maintainers

- [Bruno](https://github.com/Zahnentferner)
- [Atharva](https://github.com/Atharva0506)
See [MAINTAINERS.md](./MAINTAINERS.md) for the full list of Mentors and Maintainers for this repository.

---

Expand Down
43 changes: 43 additions & 0 deletions brand/Brand.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# ThruBox Brand Kit

This folder is the canonical source for ThruBox's visual identity: logos, favicons/icons, and color palette. All assets referenced below live in this `brand/` folder. `README.md` embeds its own copies of the two logo SVGs under `public/` — keep those in sync with the originals here if the brand mark changes.

## Logo

| Asset | File |
| --- | --- |
| ThruBox logo (SVG, with wordmark) | [`thrubox-logo.svg`](./thrubox-logo.svg) |
| AOSSIE org logo (SVG) | [`aossie-logo.svg`](./aossie-logo.svg) |

The ThruBox mark is a Menger-sponge-style cube made of green tessellated tiles wrapped around a padlock, representing an encrypted "box" relaying data between clients.

## Favicons & Icons

Generated from `thrubox-logo.svg` at the standard sizes used across browsers, bookmarks, and mobile home screens:

| File | Size | Use |
| --- | --- | --- |
| [`favicon.ico`](./favicon.ico) | 16/32/48 (multi-res) | Classic browser favicon |
| [`favicon-16x16.png`](./favicon-16x16.png) | 16×16 | Browser tab |
| [`favicon-32x32.png`](./favicon-32x32.png) | 32×32 | Browser tab (HiDPI) |
| [`favicon-48x48.png`](./favicon-48x48.png) | 48×48 | Windows taskbar |
| [`apple-touch-icon.png`](./apple-touch-icon.png) | 180×180 | iOS home screen |
| [`icon-512.png`](./icon-512.png) | 512×512 | PWA manifest / app icon |

This server itself has no bundled web UI (it's a headless REST API) — the favicons/icons here aren't consumed by any application HTML, only by the repo's own README and any external dashboards, status pages, or documentation sites built around this server.

@coderabbitai coderabbitai Bot Aug 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Correct the README consumer statement.

README.md, Lines 4-8 use the synchronized logo copies under public/. They do not consume the favicon or icon files listed in this section. State the logo consumer and the favicon/icon consumers separately.

Proposed wording 
-This server itself has no bundled web UI (it's a headless REST API) — the favicons/icons here aren't consumed by any application HTML, only by the repo's own README and any external dashboards, status pages, or documentation sites built around this server.
+This server itself has no bundled web UI (it's a headless REST API). The synchronized logo copies under `public/` are consumed by the repository README. The favicon and icon assets in this folder are available for external dashboards, status pages, or documentation sites built around this server.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@brand/Brand.md` at line 27, Update the README consumer statement in Brand.md
to distinguish the synchronized logo copies under public/—consumed by
README.md—from the favicon and icon files, which are consumed only by external
dashboards, status pages, or documentation sites. Do not state that README.md
consumes the favicon or icon files.


## Color Palette

Sourced directly from `thrubox-logo.svg` (shared with [ThruBox-Client](https://github.com/AOSSIE-Org/ThruBox-Client)):

| Swatch | Name | Hex | Usage in logo |
| --- | --- | --- | --- |
| 🟩 | ThruBox Green (light) | `#3eb03e` | Sponge tile — top face |
| 🟩 | ThruBox Green (mid) | `#228B22` | Sponge tile — front face, wordmark |
| 🟩 | ThruBox Green (dark) | `#145A14` | Sponge tile — side face |
| ⬛ | Outline | `#0f420f` | Tile stroke |
| 🟨 | Lock Gold | `#FFC517` | Padlock accent, sourced from `thrubox-logo.svg` |

## Typography

This is a non-UI project (headless Go relay server) — there is no application typography to document. The wordmark in `thrubox-logo.svg` uses `'Arial Black', system-ui, sans-serif` at weight 900 as a logotype only.
24 changes: 24 additions & 0 deletions brand/aossie-logo.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added brand/apple-touch-icon.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added brand/favicon-16x16.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added brand/favicon-32x32.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added brand/favicon-48x48.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added brand/favicon.ico
View file
Open in desktop
Binary file not shown.
Binary file added brand/icon-512.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading