ss-tools/docs/adr/ADR-0001-module-layout.md

[DEF:ADR-0001:ADR]

@STATUS ACTIVE

@PURPOSE Define the canonical project directory layout, module boundaries, and naming conventions for the ss-tools repository. This ADR is the root structural authority — all other ADRs and feature plans derive their file placement from it.

@RELATION CALLS -> [ADR-0002:ADR]

@RELATION CALLS -> [ADR-0003:ADR]

@RELATION CALLS -> [ADR-0004:ADR]

@RELATION CALLS -> [ADR-0005:ADR]

@RELATION CALLS -> [ADR-0006:ADR]

@RATIONALE A single authoritative layout prevents module sprawl, cyclic dependencies, and agent confusion during long‑horizon speckit workflows. Without this, every feature spec must re‑debate where to place files, leading to inconsistent structures and broken tooling assumptions.

@REJECTED Monorepo with per‑feature packages (e.g. packages/llm‑plugin/) — rejected because the repository has two top‑level runtime targets (Python backend, Svelte frontend) with shared Docker/configuration infrastructure. Package‑style nesting would double the directory depth without adding isolation value.

@REJECTED Flat src/ root — rejected because Python and JavaScript toolchains have incompatible project roots (pyproject.toml vs package.json), and mixing them in one top‑level src/ would force cross‑toolchain contamination.

Decision

The repository uses a two‑platform, top‑level separation:

ss-tools/                          # Repository root
├── backend/                       # Python 3.13+ / FastAPI application
│   ├── src/
│   │   ├── api/                   # FastAPI route modules (one file per route group)
│   │   ├── core/                  # Core services: task_manager, auth, migration, plugin_loader
│   │   ├── models/                # SQLAlchemy ORM models (one file per entity group)
│   │   ├── services/              # Business logic (orchestration, validators, transformers)
│   │   ├── schemas/               # Pydantic request/response schemas
│   │   └── app.py                 # FastAPI application factory
│   ├── tests/                     # pytest test suite (mirrors src/ structure)
│   ├── pyproject.toml             # Build & tool configuration
│   └── requirements.txt           # Production dependencies
├── frontend/                      # SvelteKit application
│   ├── src/
│   │   ├── routes/                # SvelteKit page routes (file‑based routing)
│   │   ├── lib/
│   │   │   ├── components/        # Reusable Svelte 5 components
│   │   │   ├── stores/            # Svelte 5 rune stores ($state)
│   │   │   └── api/               # API client modules (typed fetch wrappers)
│   │   └── i18n/                  # Internationalization dictionaries
│   ├── tests/                     # vitest test suite
│   ├── package.json               # Runtime + dev dependencies
│   ├── svelte.config.js           # SvelteKit configuration
│   └── vite.config.ts             # Vite build configuration
├── docker/                        # Dockerfiles for backend, frontend, nginx
├── docker-compose.yml             # Development Docker Compose
├── docs/
│   ├── adr/                       # Architecture Decision Records (this file)
│   ├── design/                    # Detailed design documents
│   └── ...                        # Operational docs (installation, settings, etc.)
├── specs/                         # Feature specifications (speckit artifacts)
│   └── NNN‑feature‑name/
│       ├── spec.md
│       ├── plan.md
│       ├── research.md
│       ├── data-model.md
│       ├── quickstart.md
│       ├── contracts/
│       │   └── modules.md
│       └── tasks.md
├── scripts/                       # Shell utility scripts
├── .specify/                      # Speckit workflow framework
│   ├── memory/constitution.md     # Repository constitution
│   ├── templates/                 # Speckit artifact templates
│   └── scripts/bash/              # Speckit helper scripts
├── .opencode/                     # OpenCode AI agent configuration
│   ├── command/                   # Speckit command definitions
│   ├── skills/                    # GRACE semantic protocol skills
│   └── agents/                    # Specialized agent definitions
└── .github/                       # GitHub Actions workflows

Module Boundary Rules

1. backend/src/api/ — route handlers only. Must not contain business logic, ORM queries, or schema definitions. Each file = one FastAPI APIRouter group.
2. backend/src/core/ — singleton services with application‑scoped lifetime (auth manager, task scheduler, plugin loader, migration engine). Must not import from api/.
3. backend/src/services/ — stateless or request‑scoped business logic. May depend on models/, schemas/, and core/. Must not depend on api/.
4. backend/src/models/ — SQLAlchemy ORM declarations only. No business logic, no API dependencies.
5. backend/src/schemas/ — Pydantic models for validation/serialization. No ORM dependencies, no business logic.
6. frontend/src/routes/ — SvelteKit pages. Import components from lib/components/, state from lib/stores/, API clients from lib/api/.
7. frontend/src/lib/components/ — reusable components. Must not import from routes/ (prevents circular dependencies).
8. frontend/src/lib/stores/ — Svelte 5 $state rune stores. Must not import from routes/ or components/.

File Naming Conventions

• Python modules: snake_case.py (e.g., task_manager.py, auth_provider.py)
• Svelte components: PascalCase.svelte (e.g., DashboardGrid.svelte, MappingTable.svelte)
• Test files: test_<module_name>.py or <ComponentName>.test.ts
• ADR files: ADR-NNNN-short-description.md (zero‑padded, 4 digits, kebab‑case)

Enforcement

• Speckit /speckit.plan command reads this ADR to validate proposed module placement.
• Speckit /speckit.implement rejects files written outside canonical boundaries unless justified in feature‑local research.md.
• CI static verification (python3 scripts/static_verify.py) may optionally enforce module import direction rules.

[/DEF:ADR-0001:ADR]