Chorus Technical Documentation

Getting Started #

Chorus is an open-source discussion system written in Go and React. Persistence is implemented directly on top of the Git object model in local disk storage without a relational database layer.

System Requirements

• Go: 1.22+ installed on PATH
• Node.js: 18.x or 20.x+ (npm 10.x+)
• Git: Installed on system PATH (git --version)

Local Development Setup

Execute the Go HTTP backend server and Vite React client in development mode:

# 1. Clone repository
git clone https://github.com/barissalihbabacan/Chorus.git
cd Chorus

# 2. Launch Go Backend (Port 8085)
go run ./cmd/server

# 3. Launch React Client (Port 3000)
cd web
npm install
npm run dev -- --host

Docker Execution

docker build -t chorus:latest .
docker run -d -p 8085:8085 -v chorus-data:/app/data chorus:latest

System Architecture #

The backend applies Clean Architecture boundaries to isolate HTTP transport handlers, domain services, and Git repository drivers.

Layer Responsibilities Specification

• Browser Client: Renders user interface, captures user input, and manages client-side routing.
• React SPA: Communicates via same-origin REST API requests to /api/v0.1/*.
• HTTP Router: Hostname subdomain dispatcher and endpoint routing in internal/http/router.go.
• Handlers: Parses JSON request payloads, validates input constraints, and returns HTTP status codes.
• Services: Implements domain rules (thread initialization, conversation name assignment, moderation queue).
• GitStore: Serializes domain models into filesystem paths and manages repository locking.
• Git CLI: Invokes native Git commands via Go's os/exec package.
• Git Repository: Stores immutable commit DAG objects in ./data/repository.

Expanded 9-Stage Request Lifecycle

REST API Reference #

curl -X GET https://chat.joinchorus.app/healthz

{
  "status": "ok",
  "environment": "development"
}

{
  "conversation_name": "Ash",
  "show_country": true
}

curl -X POST https://chat.joinchorus.app/api/v0.1/identities \
  -H "Content-Type: application/json" \
  -d '{"conversation_name":"Ash","show_country":true}'

{
  "id": "usr_7f8a91b2c3d4e5f6",
  "conversation_name": "Ash",
  "country": "TR",
  "created_at": "2026-07-23T14:45:00Z"
}

curl -X GET 'https://chat.joinchorus.app/api/v0.1/threads?limit=50&offset=0'

[
  {
    "id": "thd_9de587d7f3f435e2",
    "title": "Welcome to Chorus",
    "conversation_name": "Ash",
    "country": "TR",
    "created_at": "2026-07-23T10:15:34Z",
    "updated_at": "2026-07-23T10:15:34Z"
  }
]

{
  "title": "Architecture Specification",
  "body": "Discussing Clean Architecture and Git persistence.",
  "show_country": true
}

curl -X POST https://chat.joinchorus.app/api/v0.1/threads \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Architecture Specification",
    "body": "Discussing Clean Architecture and Git persistence.",
    "show_country": true
  }'

{
  "id": "thd_9de587d7f3f435e2",
  "title": "Architecture Specification",
  "conversation_name": "River",
  "country": "TR",
  "created_at": "2026-07-23T14:46:00Z",
  "updated_at": "2026-07-23T14:46:00Z"
}

{
  "body": "Implementation details match Clean Architecture conventions.",
  "show_country": true
}

curl -X POST https://chat.joinchorus.app/api/v0.1/threads/thd_9de587d7f3f435e2/messages \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Implementation details match Clean Architecture conventions.",
    "show_country": true
  }'

{
  "id": "msg_2222222222222222",
  "thread_id": "thd_9de587d7f3f435e2",
  "conversation_name": "Echo",
  "country": "DE",
  "content": "Implementation details match Clean Architecture conventions.",
  "created_at": "2026-07-23T14:47:00Z"
}

{
  "target_lang": "en"
}

curl -X POST https://chat.joinchorus.app/api/v0.1/threads/thd_9de587d7f3f435e2/messages/msg_2222222222222222/translate \
  -H "Content-Type: application/json" \
  -d '{"target_lang":"en"}'

{
  "message_id": "msg_2222222222222222",
  "original": "Implementation details match Clean Architecture conventions.",
  "translated": "Implementation details match Clean Architecture conventions.",
  "target_language": "en",
  "cached": true
}

{
  "status": "dismissed",
  "note": "Report reviewed."
}

curl -X POST https://chat.joinchorus.app/api/v0.1/moderation/reports/rpt_3333333333333333/action \
  -H "Content-Type: application/json" \
  -d '{"status":"dismissed","note":"Report reviewed."}'

{
  "id": "act_4444444444444444",
  "report_id": "rpt_3333333333333333",
  "thread_id": "thd_9de587d7f3f435e2",
  "message_id": "msg_2222222222222222",
  "status": "dismissed",
  "note": "Report reviewed.",
  "created_at": "2026-07-23T14:49:00Z"
}

Git Persistence Engine RFC Specification #

Current Implementation

The driver in internal/gitstore executes Git commit operations on local disk storage (default path: ./data/repository):

• Repository Layout: Directory trees contain thread metadata (threads/{thread_id}/metadata.json) and message streams (threads/{thread_id}/messages.jsonl).
• Commit Serialization: Thread creation and message replies execute Git commit operations via Go's os/exec package.

Planned Microbenchmarks

Microbenchmarks covering commit latency, memory allocation, and concurrency will be published prior to the Beta release using Go's test framework (go test -bench ./...).

Engineering Product Timeline #

Development phase milestones and release roadmap:

Deployment Configuration #

Chorus can be deployed as a single binary, Docker container, or systemd Linux service.

Environment Variables

• PORT: HTTP listening port (default: 8085).
• DATA_DIR: Directory path for Git storage (default: ./data/repository).
• ENV: Mode (development or production).
• TRANSLATION_API_KEY: Optional API key for translation provider.

Contributing Guide #

Guidelines for contributing code and documentation updates.

Workflow

1. Clean Architecture: Maintain strict boundaries between Handler, Service, and Repository.
2. Tests: Ensure go test -v ./... and npm run build pass clean.
3. Commits: Follow conventional commit prefixes (e.g. feat(gitstore): ...).