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
published-resource-architecture.md	Public surfaces, Publish Target Registry, publish_id (ADR-022)
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. Enterprise / AI Development Framework (docs/ai-framework/* — ADR-013, ADR-018, ADR-019)
3. This folder (docs/architecture/* and adr/*)
4. project-principles.md
5. coding-standards.md
6. testing-strategy.md
7. module-registry.md
8. provider-registry.md
9. glossary.md
10. Relevant phase docs

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