linearvoid/docs/architecture/adr/ADR-002-module-structure.md

ADR-002: Project Module / Folder Structure

Status: Accepted
Date: 2026-08-02
Author: AI Assistant (based on arc42 analysis)
Related ADRs: ADR-001, ADR-003

Context

The arc42 documentation in docs/architecture/README.md defines several clear building blocks:

• Playout Service (FFmpeg + MediaMTX/SRS, playlist handling, normalization)
• Chat Backend (WebSocket server, rooms, DMs, moderation, Redis/DB)
• Frontend SPA (hls.js player, chat UI, static assets)
• Infrastructure / Delivery (Nginx, Cloudflare R2/CDN rules, Docker, IaC)
• Supporting concerns (scripts for normalization/sync/backup, monitoring, shared utilities)

We need a folder layout that makes these modules obvious, supports independent development/deployment (Docker), keeps the root clean, and aligns with the high-level context and deployment diagrams.

Decision Drivers

1. Clear mapping to arc42 building blocks and runtime/deployment views.
2. Easy separation for frontend vs backend services.
3. Docker / container friendliness (one Dockerfile per major service).
4. Support for scripts, infrastructure-as-code, and monitoring configs.
5. Minimal cognitive load for new contributors (standard frontend/, backend/, infrastructure/ layout).
6. Future extensibility (multi-channel, ABR, LL-HLS, paid features).

Decision

Adopt the following structure (created in the workspace):

linearvoid/
├── frontend/                  # Static SPA (HTML/CSS/JS + hls.js + chat UI)
├── backend/
│   ├── playout/               # Continuous HLS playout engine (FFmpeg + MediaMTX/SRS)
│   ├── chat/                  # WebSocket chat service (Go/Node + Redis + DB)
│   └── shared/                # Common utilities, types, normalization logic
├── infrastructure/            # Docker Compose, Nginx, Cloudflare rules, IaC
├── scripts/                   # Normalization, R2 sync, backup, deployment scripts
├── monitoring/                # Dashboards, Prometheus rules, Grafana
├── docs/architecture/
│   ├── README.md              # arc42 (populated)
│   └── adr/
│       ├── ADR-001.md
│       ├── ADR-002-module-structure.md
│       └── ADR-003-tech-stack.md
├── .env.example
├── docker-compose.yml
├── README.md
└── .gitignore

Key conventions:

• backend/<service>/ contains its own src/, config/, and Dockerfile.
• infrastructure/ owns all deployment and cloud configuration.
• scripts/ holds automation that is not part of a running service.
• All documentation lives under docs/architecture/.

Rationale

• Alignment with arc42: Each top-level folder corresponds to a major building block or cross-cutting concern shown in the context and deployment diagrams.
• Developer Experience: Clear separation reduces merge conflicts and makes it obvious where to add player logic vs chat logic vs cache rules.
• Operational Simplicity: Docker Compose can easily orchestrate playout, chat, and nginx services from the root.
• Scalability: Services can be split into separate repositories or Kubernetes deployments later without major refactoring.
• Alternatives Considered:
  • Flat src/ structure → rejected (hard to see architectural boundaries).
  • Monorepo with apps/ and packages/ (Turborepo style) → overkill for current scale.
  • All-in-one services/ folder → less explicit than backend/playout vs backend/chat.

This structure was created via the create_directory tool and is reflected in the updated root and architecture READMEs.

Consequences

Positive:

• Excellent traceability from architecture docs → code.
• Easy to add new modules (e.g., backend/scheduler later).
• Supports the normalization-first and caching-first principles from ADR-001.

Negative / Risks:

• Slightly more directories than a minimal prototype (acceptable trade-off).
• Need to keep documentation in sync when structure evolves (mitigated by ADRs).

Future: Next ADRs will document Docker Compose layout (ADR-004) and API contracts between services.

References

• docs/architecture/README.md (Building Block View, Deployment View, Context Diagram)
• ADR-001 (overall architecture and technology constraints)
• ADR-003 (language and runtime choices per module)