95 lines
6.4 KiB
Markdown
95 lines
6.4 KiB
Markdown
# [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]
|