TorbatYar/docs/architecture/architecture.md

Architecture Overview — TorbatYar SuperApp

Responsibility: high-level architecture only.
Status → progress.md · Roadmap → roadmap.md · Next → 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
API-first	All interactions via versioned API / events
Multi-tenancy	Every business table has tenant_id — ADR-003
FE/BE separation	Strict — ADR-002

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

5. Non-Goals of This Document

• Implementation checklists → progress.md
• Immediate milestone → next-steps.md
• Schema columns → database-schema.md
• Endpoint tables → services-contracts.md
• How to run locally → developer-guide.md

6. Permanent Rule

Every implementation phase begins by reading:

1. docs/README.md
2. This folder (docs/architecture/* and adr/*)
3. project-principles.md
4. coding-standards.md
5. testing-strategy.md
6. module-registry.md
7. provider-registry.md
8. glossary.md
9. Relevant phase docs

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