refactor: Update documentation links for improved navigation; remove obsolete architecture file

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/`.

docs/architecture.md

@@ -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.

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
 

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.

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`
+- Module map & components: [Building Block View](docs/architecture/05_building_block_view.md)
-- Request flow & runtime interactions: `docs/architecture/06_runtime_view.md`
+- Request flow & runtime interactions: [Runtime View](docs/architecture/06_runtime_view.md)
-- Simulation roadmap & strategy: `docs/architecture/04_solution_strategy.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.

docs/architecture/README.md

@@ -22,13 +22,4 @@ Files:
 - `11_technical_risks.md`
 - `12_glossary.md`
 
-Mapping notes:
+- [quickstart](docs/quickstart.md) contains developer quickstart, migrations, testing and current status and will remain as a separate quickstart reference.
-
-- `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`.

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/`)
+- Architecture overview & chapters: [architecture](docs/architecture/README.md) (per-chapter files under `docs/architecture/`)
-- Testing & CI: `docs/architecture/14_testing_ci.md`
+- [Testing & CI](docs/architecture/14_testing_ci.md)
-- Development setup: `docs/architecture/15_development_setup.md`
+- [Development setup](docs/architecture/15_development_setup.md)
-- Implementation plan & roadmap: `docs/architecture/04_solution_strategy_extended.md`
+- Implementation plan & roadmap: [Solution strategy](docs/architecture/04_solution_strategy_extended.md)
-- Routes: `routes/` directory
+- Routes: [routes](routes/)
-- Services: `services/` directory
+- Services: [services](services/)
-- Scripts: `scripts/` directory (migrations and backfills)
+- Scripts: [scripts](scripts/) (migrations and backfills)