# ADR-002: Project Module / Folder Structure

**Status:** Accepted  
**Date:** 2026-08-02  
**Author:** AI Assistant (based on arc42 analysis)  
**Related ADRs:** [ADR-001](./ADR-001.md), [ADR-003](./ADR-003-tech-stack.md)

## 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):

```text
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)