​
Repository Structure Guide

​
Canonical Top-Level Paths

  • src/: FastAPI backend runtime.
  • frontend/: Next.js web runtime.
  • cli/: Command-line tooling package.
  • apps/: optional monorepo app scaffold (apps/api, apps/web) for future migration.
  • packages/: optional shared package scaffold (packages/simulation, packages/agents, packages/memory, packages/shared).
  • scripts/: Categorized operational and engineering scripts.
  • tests/: Pytest-discoverable test suite and test support only.
  • docs/: Canonical documentation root.
  • Transitional backend modularization lanes:
  • src/domains/*
  • src/infrastructure/*
  • src/shared/*
  • UI route ownership (which /admin vs /org-admin owns what): docs/architecture/frontend-ownership-matrix.md.

​
Script Categories

  • scripts/admin/: Administrative and account-management helpers.
  • scripts/debug/: Local debugging, verification, and repair utilities (non-pytest).
  • scripts/ops/: Operational shell scripts.
  • scripts/simulation/: Simulation execution and seeding scripts.
  • scripts/backfills/, scripts/benchmarks/, scripts/reporting/, scripts/migrations/, scripts/setup/, scripts/dev/: stable lanes for scripts by purpose (keep new scripts in the closest matching bucket).

​
Test Taxonomy Policy

  • Keep only pytest test modules (test_*.py) and shared test support (conftest.py, fixtures/helpers) under tests/.
  • Move verification, debug, cleanup, and one-off scripts to scripts/debug/.
  • Use taxonomy folders (tests/unit, tests/integration, tests/contract, tests/e2e, tests/smoke) for new tests.

​
Documentation Policy

  • docs/ is canonical.
  • Historical planning/reference docs should live in docs/archive/ or docs/reference/.
  • Avoid adding new documentation roots.

​
Commit Hygiene Policy

  • Do not commit generated/local artifacts (reports, local runtime output, one-off evidence dumps).
  • .cursor/reports/ keeps only a tracked placeholder (.gitkeep); generated reports belong in local artifacts/reports/.
  • Commit only canonical examples under docs/ when documentation value is intentional and stable.
  • Do not commit backup/temp artifacts (*.bak, *_backup.py, *.tmp, *.temp).

​
Root Hygiene Policy

Only keep canonical project entrypoints/configuration at repository root (compose, package config, CI metadata, top-level readme).

​
Compatibility Rule

During refactor, preserve runtime behavior first. Structural moves should avoid changing core application behavior and should update references in docs/automation.

​
Current Enforcement

  • Hygiene verifier (tools/repo-maintenance/verify_repo_structure.py) enforces:
  • test taxonomy directories exist
  • no debug-style files inside tests/
  • .cursor/reports/ placeholder-only policy
  • docs/node_modules and docs/package-lock.json absence
  • blocked root clutter files stay removed
  • legacy shell_scripts/ and simulation_scripts/ roots stay removed