e41ecfad4c
Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring. Co-authored-by: Cursor <cursoragent@cursor.com>
79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
# 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.
|