docs: add mkdocs, update links, add architecture documentation

docs/content/adr/0025-multitenancy-model.md

@@ -0,0 +1,49 @@
+# ADR-0025: Multi-tenancy Model
+
+## Status
+Accepted
+
+## Context
+The platform may need multi-tenancy support for SaaS deployments. Options:
+1. **Shared database with tenant_id column** - Single DB, row-level isolation
+2. **Schema-per-tenant** - Single DB, separate schemas
+3. **Database-per-tenant** - Separate databases
+
+Each has trade-offs for isolation, performance, and operational complexity.
+
+## Decision
+Use **shared database with tenant_id column** (optional feature):
+
+1. **Model**: Single PostgreSQL database with `tenant_id` column on tenant-scoped tables
+2. **Isolation**: Row-level via Ent interceptors (automatic filtering)
+3. **Tenant resolution**: From header (`X-Tenant-ID`), subdomain, or JWT claim
+4. **Optional**: Can be disabled for single-tenant deployments
+
+**Rationale:**
+- Simplest operational model (single database)
+- Good performance (can index tenant_id)
+- Easy to implement (Ent interceptors)
+- Can migrate to schema-per-tenant later if needed
+- Flexible (can support both single and multi-tenant)
+
+## Consequences
+
+### Positive
+- Simple operations (single database)
+- Good performance with proper indexing
+- Easy to implement
+- Flexible (optional feature)
+
+### Negative
+- Requires careful query design (ensure tenant_id filtering)
+- Data isolation at application level (not database level)
+- Potential for data leakage if bugs occur
+
+### Implementation Notes
+- Make tenant_id optional (nullable) for single-tenant mode
+- Add Ent interceptor to automatically filter by tenant_id
+- Resolve tenant from context via middleware
+- Add tenant_id to JWT claims
+- Document tenant isolation guarantees
+- Consider adding tenant_id to all tenant-scoped tables
+