# Architecture Overview — TorbatYar SuperApp

> **Responsibility:** high-level architecture only.  
> Status → [progress.md](../progress.md) · Roadmap → [roadmap.md](../roadmap.md) · Next → [next-steps.md](../next-steps.md)

## 1. Goals

Build a **multi-tenant**, **modular**, **API-first**, **microservice-ready** SuperApp SaaS that runs on VPS today and scales later without rewriting foundations.

## 2. Style

| Principle | Rule |
| --- | --- |
| Service-oriented | Each major capability is an independent service |
| Database-per-service | [ADR-001](adr/ADR-001.md) |
| API-first | All interactions via versioned API / events |
| Multi-tenancy | Every business table has `tenant_id` — [ADR-003](adr/ADR-003.md) |
| FE/BE separation | Strict — [ADR-002](adr/ADR-002.md) |

## 3. System Map

```
┌─────────────┐     REST/OIDC      ┌──────────────────┐
│  Frontend   │ ←────────────────→ │  Nginx (edge)    │
│  (Next.js)  │                    └────────┬─────────┘
└─────────────┘                             │
                    ┌───────────────────────┼───────────────────────┐
                    ▼                       ▼                       ▼
             Core Platform           Identity & Access           Keycloak
             (core_platform_db)      (identity_access_db)        (SSO)
                    │
                    ├── Outbox/Inbox events
                    ├── Entitlement checks
                    └── Future business services (Accounting, CRM, …)
```

## 4. Canonical Architecture Documents

| Document | Responsibility |
| --- | --- |
| [module-boundaries.md](module-boundaries.md) | What each module owns / must not own |
| [database-architecture.md](database-architecture.md) | DB ownership, isolation, migration rules |
| [multi-tenant-architecture.md](multi-tenant-architecture.md) | Tenant model, resolution, lifecycle, white-label |
| [deployment-architecture.md](deployment-architecture.md) | Runtime topology, hosts, compose |
| [security-architecture.md](security-architecture.md) | Tokens, secrets, edge TLS posture |
| [identity-architecture.md](identity-architecture.md) | SSO, OTP, user layers |
| [authorization-architecture.md](authorization-architecture.md) | Roles, entitlements, memberships |
| [integration-architecture.md](integration-architecture.md) | External providers and BFF patterns |
| [event-driven-architecture.md](event-driven-architecture.md) | Outbox/Inbox, envelope |
| [service-architecture.md](service-architecture.md) | Internal layering (API → Service → Repo) |
| [ai-architecture.md](ai-architecture.md) | AI independence rules |
| [compliance-architecture.md](compliance-architecture.md) | Audit, posting engine, regulated flows |
| [adr/](adr/) | Architecture Decision Records |

## 5. Non-Goals of This Document

- Implementation checklists → [progress.md](../progress.md)
- Immediate milestone → [next-steps.md](../next-steps.md)
- Schema columns → [database-schema.md](../reference/database-schema.md)
- Endpoint tables → [services-contracts.md](../reference/services-contracts.md)
- How to run locally → [developer-guide.md](../development/developer-guide.md)

## 6. Permanent Rule

Every implementation phase begins by reading:

1. [docs/README.md](../README.md)
2. [AI Development Framework](../ai-framework/README.md) (`docs/ai-framework/*`)
3. This folder (`docs/architecture/*` and `adr/*`)
4. [project-principles.md](../development/project-principles.md)
5. [coding-standards.md](../development/coding-standards.md)
6. [testing-strategy.md](../development/testing-strategy.md)
7. [module-registry.md](../module-registry.md)
8. [provider-registry.md](../provider-registry.md)
9. [glossary.md](../glossary.md)
10. Relevant [phase docs](../phases/)

If architecture, APIs, providers, or module boundaries change: **update documentation first**, then implement.