docs: add initial adrs and nav (#550)

Author: shayancoin

docs/adrs/adr-0001-platform-foundation.md

@@ -0,0 +1,15 @@
+# ADR 0001: Platform Foundation and Documentation Stack
+
+## Status
+Accepted
+
+## Context
+The project consolidates multiple services, documentation, and operational guides intended to onboard engineers rapidly. We needed a consistent documentation platform capable of integrating backend, frontend, and DevOps guidance while supporting Markdown authoring, custom styling, and diagrams.
+
+## Decision
+We standardize on **MkDocs Material** as the documentation engine and keep all narrative and architectural documentation within the `docs/` directory. ADRs, runbooks, and onboarding guides follow Markdown conventions and leverage MkDocs features (admonitions, syntax highlighting, and navigation tabs) to present cohesive guidance.
+
+## Consequences
+- Contributors can document decisions using Markdown without additional tooling.
+- Documentation builds remain reproducible via `mkdocs serve` and `mkdocs build`.
+- Any new architectural decision records must be added under `docs/adrs/` and referenced in `mkdocs.yml` to surface in the navigation menu.

docs/adrs/adr-0002-service-architecture.md

@@ -0,0 +1,15 @@
+# ADR 0002: Service-Oriented Application Layout
+
+## Status
+Accepted
+
+## Context
+The platform serves multiple personas (administrators, analysts, and external applications) and requires separation between the API, admin tooling, and public frontend. A monolithic structure would slow independent deployment and testing.
+
+## Decision
+We organize the codebase into discrete service directories (`backend/`, `frontend/`, `supabase/`, and specialized tooling) with shared libraries under `packages/`. Each service exposes its own deployment pipeline while sharing infrastructure definitions through Docker Compose and Terraform modules.
+
+## Consequences
+- Teams can develop and deploy components independently while reusing shared utilities.
+- CI/CD pipelines can target specific services for faster feedback loops.
+- Cross-service changes require coordination through clearly versioned shared packages and documentation updates.

docs/adrs/adr-0003-supabase-integration.md

@@ -0,0 +1,15 @@
+# ADR 0003: Supabase for Managed Auth and Data Storage
+
+## Status
+Accepted
+
+## Context
+We require a hosted persistence and authentication layer that integrates with the frontend quickly, supports row-level security, and provides realtime capabilities without building bespoke infrastructure.
+
+## Decision
+We adopt Supabase to provide PostgreSQL storage, authentication flows, and policy management. The `supabase/` directory houses configuration, migrations, and policy definitions, which are synchronized through CLI tooling and referenced in the docs for contributors.
+
+## Consequences
+- Supabase delivers managed authentication, storage, and realtime subscriptions with minimal setup.
+- Local development requires developers to run the Supabase stack via Docker Compose or connect to managed instances.
+- Architectural changes impacting data models must be reflected in Supabase migrations and documented policies.

mkdocs.yml

@@ -37,6 +37,10 @@ nav:
   - Docker and Deployment: docker-deployment.md
   - Release Checklist: release-checklist.md
   - Architecture: ARCHITECTURE.md
+  - ADRs:
+      - Platform Foundation and Documentation Stack: adrs/adr-0001-platform-foundation.md
+      - Service-Oriented Application Layout: adrs/adr-0002-service-architecture.md
+      - Supabase for Managed Auth and Data Storage: adrs/adr-0003-supabase-integration.md
   - API Spec: API_SPEC.md
   - AI Engine: AI_ENGINE.md
   - GLB Asset Standard: GLB_ASSET_STANDARD.md