restruc

.github/workflows/deploy-docs.yml

@@ -37,7 +37,7 @@ jobs:
           cache: "pip"
 
       - name: Install dependencies
-        run: pip install mkdocs mkdocs-material mkdocs-glightbox mkdocs-panzoom-plugin
+        run: pip install mkdocs mkdocs-material mkdocs-glightbox mkdocs-panzoom-plugin mkdocs-minify-plugin
 
       - name: Build site
         run: mkdocs build

README.md

@@ -22,26 +22,19 @@ pipeline notes) lives under `docs/`.
 
 Website + backend (active stack):
 
-- [Getting Started](docs/website/getting-started.md)
+- [Getting Started](docs/web/getting-started.md)
-- [Architecture](docs/architecture.md)
+- [Architecture](docs/web/architecture.md)
-- [Database](docs/website/database.md)
+- [Database](docs/web/database.md)
-- [Docker Guide](docs/website/docker.md)
+- [Docker Guide](docs/web/docker.md)
-- [Testing](docs/website/testing.md)
+- [Testing](docs/web/testing.md)
-- [Environment Variables](docs/website/environment-variables.md)
+- [Environment Variables](docs/web/environment-variables.md)
-- [Token Validation](docs/website/token-validation.md)
+- [Token Validation](docs/web/token-validation.md)
 
 Data generation pipeline (C++):
 
 - [Pipeline README](docs/pipeline/README.md)
 - [Ethics & Known Issues](docs/pipeline/ETHICS-AND-KNOWN-ISSUES.md)
 
-## Diagrams
-
-- [Architecture](docs/website/diagrams-out/architecture.svg)
-- [Deployment](docs/website/diagrams-out/deployment.svg)
-- [Authentication Flow](docs/website/diagrams-out/authentication-flow.svg)
-- [Database Schema](docs/website/diagrams-out/database-schema.svg)
-
 ## Current status
 
 Active areas in the repository:
@@ -76,12 +69,12 @@ Archived/reference areas:
 - Node.js 18 or later
 - Docker Desktop, or an equivalent Docker Engine setup
 
-See [Getting Started](docs/website/getting-started.md) for the full
+See [Getting Started](docs/web/getting-started.md) for the full
 prerequisite list, including the pipeline's C++ toolchain.
 
 ## Quick start
 
-For full setup details, use [Getting Started](docs/website/getting-started.md).
+For full setup details, use [Getting Started](docs/web/getting-started.md).
 This section is the shortest path to a working dev environment.
 
 ### Full stack (Docker)
@@ -131,9 +124,8 @@ tooling/
   pipeline/         C++20 seed-data generation CLI (CMake)
 
 docs/
-  architecture.md   High-level architecture overview
+  web/              Architecture, setup, docker, testing, diagrams
-  website/          Backend/frontend setup, docker, testing, diagrams
+  pipeline/         Pipeline docs, ethics notes, diagrams
-  pipeline/         Pipeline docs, ethics notes, PlantUML diagrams
 
 archive/
   next-js-web-app/  Older Next.js frontend (reference only)
@@ -151,7 +143,7 @@ docker compose --env-file web/.env.test -f web/docker-compose.test.yaml up --abo
 
 The same command runs in CI via
 [`.github/workflows/tests.yml`](.github/workflows/tests.yml) on every push
-and pull request to `main`. See [Testing](docs/website/testing.md) for the
+and pull request to `main`. See [Testing](docs/web/testing.md) for the
 full command list.
 
 ## Configuration
@@ -163,14 +155,14 @@ Common active variables:
   `WEBSITE_BASE_URL`
 - Frontend runtime: `API_BASE_URL`, `SESSION_SECRET`, `NODE_ENV`
 
-See [Environment Variables](docs/website/environment-variables.md) for details.
+See [Environment Variables](docs/web/environment-variables.md) for details.
 
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
 3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Run the checks in [Testing](docs/website/testing.md) (backend tests,
+4. Run the checks in [Testing](docs/web/testing.md) (backend tests,
    `npm run lint`, `npm run typecheck`)
 5. Push to the branch (`git push origin feature/amazing-feature`)
 6. Open a Pull Request

docs/index.md

@@ -10,6 +10,6 @@ Welcome to the documentation for The Biergarten App.
 
 ## Documentation Sections
 
-- **[Architecture](architecture.md)** — System design and components
+- **[Architecture](web/architecture.md)** — System design and components
-- **[Website](website/getting-started.md)** — Backend and frontend documentation
+- **[Website](web/getting-started.md)** — Backend and frontend documentation
 - **[Pipeline](pipeline/README.md)** — Data pipeline and ETL processes

docs/pipeline/README.md

@@ -302,11 +302,11 @@ see ETHICS-AND-KNOWN-ISSUES.md's Names-by-Country Dataset section.
 
 ### Process flow - activity diagram
 
-![An activity diagram](./diagrams/current/output/activity.svg)
+See [Activity diagram](./diagrams/current/activity.md).
 
 ### Architectural overview - class diagram
 
-![A class diagram](./diagrams/current/output/class.svg)
+See [Class diagram](./diagrams/current/class.md).
 
 ---
 

docs/pipeline/diagrams/current/activity.md

@@ -3,5 +3,5 @@
 The only concurrency in the current pipeline is a dedicated log dispatcher thread that drains `log_channel` and forwards entries to spdlog for the entire run (joined during shutdown after `log_channel` closes). `BiergartenPipelineOrchestrator::Run()` itself is synchronous — sampling, enrichment, generation, and export all happen on the main thread.
 
 ```mermaid
---8<-- "diagrams/pipeline/current/activity.mmd"
+--8<-- "pipeline/diagrams/current/activity.mmd"
 ```

docs/pipeline/diagrams/current/class.md

@@ -1,5 +1,5 @@
 # The Biergarten Data Pipeline — Class Diagram (Current)
 
 ```mermaid
---8<-- "diagrams/pipeline/current/class.mmd"
+--8<-- "pipeline/diagrams/current/class.mmd"
 ```

docs/pipeline/diagrams/planned/activity.md

@@ -3,5 +3,5 @@
 Each generation phase runs a producer/consumer trio concurrently: an **Orchestrator** producer feeds a bounded channel, an **LLM Worker** consumes it and generates records (closing its output channel when the input is drained and closed), and a **SQLite Worker** consumes that output channel and commits in batches. The Checkin and Follow phases run in parallel with each other once the user and brewery pools are populated.
 
 ```mermaid
---8<-- "diagrams/pipeline/planned/activity.mmd"
+--8<-- "pipeline/diagrams/planned/activity.mmd"
 ```

docs/pipeline/diagrams/planned/class.md

@@ -1,7 +1,7 @@
 # Biergarten Data Pipeline — Class Diagram (Planned)
 
 ```mermaid
---8<-- "diagrams/pipeline/planned/class.mmd"
+--8<-- "pipeline/diagrams/planned/class.mmd"
 ```
 
 ## Notes

docs/web/architecture.md

@@ -19,27 +19,25 @@ reference.
 
 For visual representations, see:
 
-- [architecture.svg](website/diagrams-out/architecture.svg) - Vertical-slice
+- [Vertical Slice](diagrams/vertical-slice.md) - host wiring and project
-  architecture diagram
+  reference diagrams
-- [deployment.svg](website/diagrams-out/deployment.svg) - Docker deployment
+- [Deployment](diagrams/deployment.md) - Docker deployment diagram
-  diagram
+- [Database Schema](diagrams/database-schema.md) - database relationships
-- [database-schema.svg](website/diagrams-out/database-schema.svg) - Database
-  relationships
 
 Authentication workflow diagrams, one per flow, under
-`website/diagrams-out/auth/`:
+[`diagrams/auth/`](diagrams/auth/):
 
-- [registration.svg](website/diagrams-out/auth/registration.svg)
+- [Registration](diagrams/auth/registration.md)
-- [login.svg](website/diagrams-out/auth/login.svg)
+- [Login](diagrams/auth/login.md)
-- [refresh-token.svg](website/diagrams-out/auth/refresh-token.svg)
+- [Refresh Token](diagrams/auth/refresh-token.md)
-- [confirm-user.svg](website/diagrams-out/auth/confirm-user.svg)
+- [Confirm User](diagrams/auth/confirm-user.md)
-- [resend-confirmation.svg](website/diagrams-out/auth/resend-confirmation.svg)
+- [Resend Confirmation](diagrams/auth/resend-confirmation.md)
-- [update-username.svg](website/diagrams-out/auth/update-username.svg)
+- [Update Username](diagrams/auth/update-username.md)
-- [update-email.svg](website/diagrams-out/auth/update-email.svg)
+- [Update Email](diagrams/auth/update-email.md)
-- [update-password.svg](website/diagrams-out/auth/update-password.svg)
+- [Update Password](diagrams/auth/update-password.md)
-- [update-profile.svg](website/diagrams-out/auth/update-profile.svg)
+- [Update Profile](diagrams/auth/update-profile.md)
-- [delete-account.svg](website/diagrams-out/auth/delete-account.svg)
+- [Delete Account](diagrams/auth/delete-account.md)
-- [error-handling.svg](website/diagrams-out/auth/error-handling.svg) - shared
+- [Error Handling](diagrams/auth/error-handling.md) - shared
   `GlobalExceptionFilter` mapping used by all flows above
 
 ## Backend architecture
@@ -370,7 +368,7 @@ method that registers its repository and slice-internal services
 - Application focuses on orchestration; the database enforces integrity via
   keys, `CHECK` constraints, and cascades
 
-See [Database](website/database.md) for the schema and the app's SQL
+See [Database](database.md) for the schema and the app's SQL
 error-handling approach in more detail.
 
 ## Frontend architecture
@@ -504,7 +502,7 @@ reference. Product and engineering documentation points to `web/frontend`.
 ## Database architecture
 
 For the table-by-table schema and the custom SQL error code scheme, see
-[Database](website/database.md).
+[Database](database.md).
 
 ### SQL-first philosophy
 
@@ -555,7 +553,7 @@ tracking stays valid.
 **Purpose**: Populate development/test databases with realistic data
 
 **Implementation**: `Database.Seed` project, using data produced by the C++
-pipeline under `tooling/pipeline/` (see [Pipeline README](pipeline/README.md))
+pipeline under `tooling/pipeline/` (see [Pipeline README](../pipeline/README.md))
 
 **Seed Data**:
 
@@ -590,7 +588,7 @@ Tables that exist in the schema but have no repository yet (`UserAvatar`,
 - Testing (`docker-compose.test.yaml`)
 - Production (`docker-compose.prod.yaml`)
 
-For details, see [Docker Guide](website/docker.md).
+For details, see [Docker Guide](docker.md).
 
 ### Health checks
 
@@ -626,4 +624,4 @@ flowchart TB
 - Mock external dependencies
 - Test database for integration tests
 
-For details, see [Testing Guide](website/testing.md).
+For details, see [Testing Guide](testing.md).

docs/web/database.md

@@ -11,7 +11,7 @@ tags:
 
 SQL Server 2022 schema, migration approach, and the app's SQL error-handling
 convention. For the vertical-slice code that talks to this schema, see
-[Architecture](../architecture.md).
+[Architecture](architecture.md).
 
 ## Schema
 
@@ -42,7 +42,7 @@ script per table.
 
 Each script is run in order by `Database.Migrations` (DbUp) on startup. Each
 table is queried directly by the owning feature slice's repository (see
-[Direct SQL via Dapper/ADO.NET](../architecture.md#direct-sql-via-dapperadonet)).
+[Direct SQL via Dapper/ADO.NET](architecture.md#direct-sql-via-dapperadonet)).
 
 A generated DBML copy of the schema (for import into a diagramming tool such as
 dbdiagram.io) lives at `web/backend/Database/Database.Migrations/schema.dbml`.

docs/web/diagrams/auth/confirm-user.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Confirm User
 
 ```mermaid
---8<-- "diagrams/website/auth/confirm-user.mmd"
+--8<-- "web/diagrams/auth/confirm-user.mmd"
 ```

docs/web/diagrams/auth/delete-account.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Delete Account
 
 ```mermaid
---8<-- "diagrams/website/auth/delete-account.mmd"
+--8<-- "web/diagrams/auth/delete-account.mmd"
 ```

docs/web/diagrams/auth/error-handling.md

@@ -3,5 +3,5 @@
 Global exception mapping performed by `API.Core`'s `GlobalExceptionFilter`. Applies uniformly across every authentication endpoint (registration, login, refresh, confirm, resend, update-username/email/password/profile, delete-account) — see the per-flow diagrams for where each exception type is thrown.
 
 ```mermaid
---8<-- "diagrams/website/auth/error-handling.mmd"
+--8<-- "web/diagrams/auth/error-handling.mmd"
 ```

docs/web/diagrams/auth/login.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Login
 
 ```mermaid
---8<-- "diagrams/website/auth/login.mmd"
+--8<-- "web/diagrams/auth/login.mmd"
 ```

docs/web/diagrams/auth/refresh-token.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Refresh Token
 
 ```mermaid
---8<-- "diagrams/website/auth/refresh-token.mmd"
+--8<-- "web/diagrams/auth/refresh-token.mmd"
 ```

docs/web/diagrams/auth/registration.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Registration
 
 ```mermaid
---8<-- "diagrams/website/auth/registration.mmd"
+--8<-- "web/diagrams/auth/registration.mmd"
 ```

docs/web/diagrams/auth/resend-confirmation.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Resend Confirmation Email
 
 ```mermaid
---8<-- "diagrams/website/auth/resend-confirmation.mmd"
+--8<-- "web/diagrams/auth/resend-confirmation.mmd"
 ```

docs/web/diagrams/auth/update-email.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Update Email
 
 ```mermaid
---8<-- "diagrams/website/auth/update-email.mmd"
+--8<-- "web/diagrams/auth/update-email.mmd"
 ```

docs/web/diagrams/auth/update-password.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Update Password
 
 ```mermaid
---8<-- "diagrams/website/auth/update-password.mmd"
+--8<-- "web/diagrams/auth/update-password.mmd"
 ```

docs/web/diagrams/auth/update-profile.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Update Profile
 
 ```mermaid
---8<-- "diagrams/website/auth/update-profile.mmd"
+--8<-- "web/diagrams/auth/update-profile.mmd"
 ```

docs/web/diagrams/auth/update-username.md

@@ -1,5 +1,5 @@
 # User Authentication Flow — Update Username
 
 ```mermaid
---8<-- "diagrams/website/auth/update-username.mmd"
+--8<-- "web/diagrams/auth/update-username.mmd"
 ```

docs/web/diagrams/database-schema.md

@@ -3,5 +3,5 @@
 Every table also has a `RowVersion ROWVERSION` column (optimistic concurrency), omitted below for brevity. Tables marked `(*)` have no repository/feature slice yet.
 
 ```mermaid
---8<-- "diagrams/website/database-schema.mmd"
+--8<-- "web/diagrams/database-schema.mmd"
 ```

docs/web/diagrams/deployment.md

@@ -1,7 +1,7 @@
 # Docker Deployment Architecture
 
 ```mermaid
---8<-- "diagrams/website/deployment.mmd"
+--8<-- "web/diagrams/deployment.mmd"
 ```
 
 ## Notes

docs/web/diagrams/vertical-slice.md

@@ -11,7 +11,7 @@ assemblies to register — there's no shared bootstrap. `Database.Migrations`
 doesn't wire up any slice; it applies schema directly.
 
 ```mermaid
---8<-- "diagrams/website/architecture/host-wiring.mmd"
+--8<-- "web/diagrams/vertical-slice/host-wiring.mmd"
 ```
 
 ## Project reference dependencies
@@ -25,7 +25,7 @@ foundation projects (`Shared.Contracts`, `Domain.Entities`,
 see the notes for what else each of those foundation projects pulls in.
 
 ```mermaid
---8<-- "diagrams/website/architecture/project-references.mmd"
+--8<-- "web/diagrams/vertical-slice/project-references.mmd"
 ```
 
 ## Notes

docs/web/docker.md

@@ -21,7 +21,7 @@ The project uses Docker Compose to orchestrate multiple services:
 - React Router website (SSR frontend)
 - Test runners
 
-See the [deployment diagram](diagrams-out/deployment.svg) for visual
+See the [deployment diagram](diagrams/deployment.md) for visual
 representation.
 
 ## Docker Compose environments

docs/web/getting-started.md

@@ -159,6 +159,6 @@ reference; it is not part of the running stack.
 
 ## Next steps
 
-- Review [Architecture](../architecture.md)
+- Review [Architecture](architecture.md)
 - Run backend and frontend checks from [Testing](testing.md)
 - Use [Docker Guide](docker.md) for container troubleshooting

mkdocs.yml

@@ -7,48 +7,54 @@ theme:
   name: material
 nav:
   - Home: index.md
-  - Architecture: architecture.md
+  - Web:
-  - Diagrams:
+      - Architecture: web/architecture.md
-      - Website:
+      - Getting Started: web/getting-started.md
-          - Architecture: website/diagrams/architecture.md
+      - Database: web/database.md
-          - Database Schema: website/diagrams/database-schema.md
+      - Docker: web/docker.md
-          - Deployment: website/diagrams/deployment.md
+      - Environment Variables: web/environment-variables.md
+      - Testing: web/testing.md
+      - Token Validation: web/token-validation.md
+      - Diagrams:
+          - Vertical Slice: web/diagrams/vertical-slice.md
+          - Database Schema: web/diagrams/database-schema.md
+          - Deployment: web/diagrams/deployment.md
           - Auth Flows:
-              - Registration: website/diagrams/auth/registration.md
+              - Registration: web/diagrams/auth/registration.md
-              - Login: website/diagrams/auth/login.md
+              - Login: web/diagrams/auth/login.md
-              - Refresh Token: website/diagrams/auth/refresh-token.md
+              - Refresh Token: web/diagrams/auth/refresh-token.md
-              - Confirm User: website/diagrams/auth/confirm-user.md
+              - Confirm User: web/diagrams/auth/confirm-user.md
-              - Resend Confirmation: website/diagrams/auth/resend-confirmation.md
+              - Resend Confirmation: web/diagrams/auth/resend-confirmation.md
-              - Update Username: website/diagrams/auth/update-username.md
+              - Update Username: web/diagrams/auth/update-username.md
-              - Update Email: website/diagrams/auth/update-email.md
+              - Update Email: web/diagrams/auth/update-email.md
-              - Update Password: website/diagrams/auth/update-password.md
+              - Update Password: web/diagrams/auth/update-password.md
-              - Update Profile: website/diagrams/auth/update-profile.md
+              - Update Profile: web/diagrams/auth/update-profile.md
-              - Delete Account: website/diagrams/auth/delete-account.md
+              - Delete Account: web/diagrams/auth/delete-account.md
-              - Error Handling: website/diagrams/auth/error-handling.md
+              - Error Handling: web/diagrams/auth/error-handling.md
-      - Pipeline:
+  - Pipeline:
+      - Overview: pipeline/README.md
+      - Roadmap: pipeline/ROADMAP.md
+      - Ethics & Known Issues: pipeline/ETHICS-AND-KNOWN-ISSUES.md
+      - Diagrams:
           - Current:
               - Activity: pipeline/diagrams/current/activity.md
               - Class: pipeline/diagrams/current/class.md
           - Planned:
               - Activity: pipeline/diagrams/planned/activity.md
               - Class: pipeline/diagrams/planned/class.md
-  - Website:
-      - Getting Started: website/getting-started.md
-      - Database: website/database.md
-      - Docker: website/docker.md
-      - Environment Variables: website/environment-variables.md
-      - Testing: website/testing.md
-      - Token Validation: website/token-validation.md
-  - Pipeline:
-      - Overview: pipeline/README.md
-      - Roadmap: pipeline/ROADMAP.md
-      - Ethics & Known Issues: pipeline/ETHICS-AND-KNOWN-ISSUES.md
 
 plugins:
   - search
   - glightbox
   - panzoom:
       mermaid: true
+  - minify:
+      minify_html: true
+      minify_js: true
+      minify_css: true
+      htmlmin_opts:
+        remove_comments: true
+      cache_safe: true
 
 markdown_extensions:
   - pymdownx.superfences: