diff --git a/README.md b/README.md index 51052d7..db39740 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,8 @@ A range of features are implemented to support these functionalities. ## Documentation & quickstart -This repository contains detailed developer and architecture documentation in the `docs/` folder. For a short quickstart, troubleshooting notes, migration/backfill instructions and the current implementation status, see `docs/quickstart.md`. +This repository contains detailed developer and architecture documentation in the `docs/` folder. For a short quickstart, troubleshooting notes, migration/backfill instructions and the current implementation status, see [quickstart](docs/quickstart.md). -Key architecture documents: see `docs/architecture/README.md` for the arc42-based architecture documentation. +Key architecture documents: see [architecture](docs/architecture/README.md) for the arc42-based architecture documentation. For contributors: the `routes/`, `models/` and `services/` folders contain the primary application code. Tests and E2E specs are in `tests/`. diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index ca01024..0000000 --- a/docs/architecture.md +++ /dev/null @@ -1,41 +0,0 @@ -# Architecture Documentation - -This folder contains the project's architecture documents split into arc42-inspired chapters (Markdown). - -Start here (per-chapter files live under `docs/architecture/`): - -- `docs/architecture/README.md` — mapping and next steps (overview of the chapter layout) -- `docs/architecture/01_introduction_and_goals.md` — overview and runtime flow -- `docs/architecture/02_architecture_constraints.md` — constraints -- `docs/architecture/03_context_and_scope.md` — context and external actors -- `docs/architecture/04_solution_strategy.md` — solution strategy and simulation roadmap -- `docs/architecture/04_solution_strategy_extended.md` — implementation plan & MVP roadmap -- `docs/architecture/05_building_block_view.md` — system components and static structure -- `docs/architecture/06_runtime_view.md` — reporting pipeline and runtime interactions -- `docs/architecture/07_deployment_view.md` — deployment and infrastructure notes -- `docs/architecture/08_concepts.md` — domain concepts and data model -- `docs/architecture/09_architecture_decisions.md` — architecture decision records -- `docs/architecture/10_quality_requirements.md` — quality targets and checks -- `docs/architecture/11_technical_risks.md` — technical risks and mitigations -- `docs/architecture/12_glossary.md` — glossary -- `docs/architecture/13_ui_and_style.md` — UI templates, macros and style guidance -- `docs/architecture/14_testing_ci.md` — testing strategy and CI guidance -- `docs/architecture/15_development_setup.md` — local development setup - -Overview (migrated content): - -This repository includes an architecture overview that complements the chapter files above and maps high-level module layout and request flow into the per-chapter documents. - -Key pointers: - -- Module map & components: `docs/architecture/05_building_block_view.md` -- Request flow & runtime interactions: `docs/architecture/06_runtime_view.md` -- Simulation roadmap & strategy: `docs/architecture/04_solution_strategy.md` - -Developer quickstart, migrations, testing and current implementation status remain in `docs/quickstart.md` (canonical quickstart). If you prefer, the quickstart can be split into specific chapters, but currently it serves as a single onboarding document. - -To continue expanding the architecture docs: - -1. Open the chapter file you want to expand under `docs/architecture/`. -2. Move or add content from other docs into the chapter and ensure the chapter references code files (e.g., `services/simulation.py`, `routes/reporting.py`) using relative links. -3. After edits, run `scripts/check_docs_links.py` to validate local links. diff --git a/docs/architecture/01_introduction_and_goals.md b/docs/architecture/01_introduction_and_goals.md index cca91fb..f7d3db9 100644 --- a/docs/architecture/01_introduction_and_goals.md +++ b/docs/architecture/01_introduction_and_goals.md @@ -20,11 +20,11 @@ Frontend components are server-rendered Jinja2 templates, with Chart.js powering ### Current implementation status (summary) -- Currency normalization, simulation scaffold, and reporting service exist; see `docs/quickstart.md` for full status and migration instructions. +- Currency normalization, simulation scaffold, and reporting service exist; see [quickstart](docs/quickstart.md) for full status and migration instructions. ## MVP Features (migrated) -The following MVP features and priorities were migrated from `docs/mvp.md`. +The following MVP features and priorities were defined during initial planning. ### Prioritized Features diff --git a/docs/architecture/04_solution_strategy_extended.md b/docs/architecture/04_solution_strategy_extended.md index bdf97de..236dc47 100644 --- a/docs/architecture/04_solution_strategy_extended.md +++ b/docs/architecture/04_solution_strategy_extended.md @@ -1,6 +1,6 @@ # Implementation Plan (extended) -This file contains the migrated implementation plan (MVP features, steps, and estimates) originally in `docs/implementation_plan.md`. +This file contains the implementation plan (MVP features, steps, and estimates). ## Project Setup @@ -126,4 +126,4 @@ Goal: Identify core MVP features, acceptance criteria, and quick estimates. 1. Scaffold Reporting endpoints (`services/reporting.py`, `routes/reporting.py`, front-end Dashboard, tests). 1. Add CI job for tests and coverage. -See `docs/architecture/13_ui_and_style.md` for the UI template audit, layout guidance, and next steps. +See [UI and Style](docs/architecture/13_ui_and_style.md) for the UI template audit, layout guidance, and next steps. diff --git a/docs/architecture/05_building_block_view.md b/docs/architecture/05_building_block_view.md index 59b1dbf..51d934e 100644 --- a/docs/architecture/05_building_block_view.md +++ b/docs/architecture/05_building_block_view.md @@ -23,12 +23,12 @@ Explain the static structure: modules, components, services and their relationsh ## Architecture overview (migrated) -This overview complements `docs/architecture.md` with a high-level map of CalMiner's module layout and request flow. +This overview complements [architecture](docs/architecture/README.md) with a high-level map of CalMiner's module layout and request flow. Refer to the detailed architecture chapters in `docs/architecture/`: -- Module map & components: `docs/architecture/05_building_block_view.md` -- Request flow & runtime interactions: `docs/architecture/06_runtime_view.md` -- Simulation roadmap & strategy: `docs/architecture/04_solution_strategy.md` +- Module map & components: [Building Block View](docs/architecture/05_building_block_view.md) +- Request flow & runtime interactions: [Runtime View](docs/architecture/06_runtime_view.md) +- Simulation roadmap & strategy: [Solution Strategy](docs/architecture/04_solution_strategy.md) -Currency normalization and backfill tooling have been added (see `scripts/backfill_currency.py` and related migrations) to support canonical currency lookups across cost tables. +Currency normalization and backfill tooling have been added (see [backfill_currency.py](scripts/backfill_currency.py) and related migrations) to support canonical currency lookups across cost tables. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 521ef62..8b49e38 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -22,13 +22,4 @@ Files: - `11_technical_risks.md` - `12_glossary.md` -Mapping notes: - -- `docs/architecture.md` and `docs/architecture_overview.md` contain high-level content that will be split into these chapter files. -- `docs/quickstart.md` contains developer quickstart, migrations, testing and current status and will remain as a separate quickstart reference. - -Next steps: - -1. Move relevant sections from `docs/architecture.md` and `docs/architecture_overview.md` into the appropriate chapter files. -2. Expand each chapter with diagrams, examples, and references to code (files and modules). -3. Add links from the top-level `README.md` to `docs/architecture/README.md` and `docs/quickstart.md`. +- [quickstart](docs/quickstart.md) contains developer quickstart, migrations, testing and current status and will remain as a separate quickstart reference. diff --git a/docs/quickstart.md b/docs/quickstart.md index 8fdb390..5cc6215 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -74,10 +74,10 @@ The database contains tables such as `capex`, `opex`, `chemical_consumption`, `f ## Where to look next -- Architecture overview & chapters: `docs/architecture.md` (per-chapter files under `docs/architecture/`) -- Testing & CI: `docs/architecture/14_testing_ci.md` -- Development setup: `docs/architecture/15_development_setup.md` -- Implementation plan & roadmap: `docs/architecture/04_solution_strategy_extended.md` -- Routes: `routes/` directory -- Services: `services/` directory -- Scripts: `scripts/` directory (migrations and backfills) +- Architecture overview & chapters: [architecture](docs/architecture/README.md) (per-chapter files under `docs/architecture/`) +- [Testing & CI](docs/architecture/14_testing_ci.md) +- [Development setup](docs/architecture/15_development_setup.md) +- Implementation plan & roadmap: [Solution strategy](docs/architecture/04_solution_strategy_extended.md) +- Routes: [routes](routes/) +- Services: [services](services/) +- Scripts: [scripts](scripts/) (migrations and backfills)