busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
f9d2f8d9bc3a5ef548d88d616e24137cc4ee1815
ss-tools/docs/adr/ADR-0001-module-layout.md
busya e7bac04e98 feat(dashboard-testing): add reference URL baseline workflow and analyst UX 
Discover dashboard filters, datasets and metrics from a parsed reference URL; capture and review baseline candidates with source provenance. Improve scenario DAG and run result views, add isolated browser coverage, and align contracts and ADRs.
2026-09-25 10:36:37 +03:00

3.0 KiB
Raw Blame History

@{ Doc.Adr.ADR0001 [C:1] [TYPE ADR]

@STATUS PARTIALLY IMPLEMENTED

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

@RELATION CALLS -> [Doc.Adr.ADR0002]

@RELATION CALLS -> [Doc.Adr.ADR0003]

@RELATION CALLS -> [Doc.Adr.ADR0016]

@RELATION CALLS -> [Doc.Adr.ADR0005]

@RELATION CALLS -> [Doc.Adr.ADR0006]

@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 keeps separate Python and Svelte application roots:

  • backend/src/ contains the FastAPI app, API routes, core infrastructure, domain services, models, schemas, MCP tools and in-process plugins. backend/tests/ contains Python tests.
  • frontend/src/ contains Svelte routes, reusable lib/ components, models, stores and API clients. Frontend tests live beside components and under frontend/e2e/.
  • specs/ contains feature contracts and evidence; docs/adr/ contains durable architectural decisions. docker/, Compose files and root scripts define deployment and local development.
  • .agents/skills/ and .agents/agents/ are canonical semantic sources; .kilo/ contains synchronized runtime copies. See root AGENTS.md for current startup, verification and sync commands.

Import direction is the durable rule: backend domain services must not depend on FastAPI route modules; frontend lib/ code must not depend on route files. Domain models and schemas should stay independent of API transport. New files follow the language toolchain's normal naming conventions.

Current limits

The old fixed tree, Python-version pin, .opencode/-only agent layout and claim that /speckit.implement automatically rejects misplaced files described an earlier plan. They are not enforcement mechanisms today. Placement is checked in review and by the relevant feature contract; this ADR does not require every feature to have the same set of Speckit files. Existing modules may need incremental extraction before the ideal import direction is fully enforced, so status remains PARTIALLY IMPLEMENTED.

@} Doc.Adr.ADR0001