Mortezakoohjani e41ecfad4c Sync platform docs, infra, and module services with Accounting integration.

Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-25 22:35:23 +03:30

122 KiB

Raw Blame History

Master Architecture Report — TorbatYar SuperApp

Field	Value
Document	Master Architecture Report
Version	1.0
Date	2026-07-24
Classification	Internal — Enterprise Planning
Status	Synthesis for review
Scope	Platform + Accounting + planned modules
Sources	Canonical docs under `docs/` (architecture, progress, roadmap, registries, frontend, deployment, phases, decisions, reference). Folder `docs/architecture-review/` did not previously contain intermediate review packs; this master report synthesizes the live documentation set.

Document Control

Purpose

This report consolidates TorbatYar’s architecture, delivery maturity, platform services, business modules, risks, and enterprise roadmap into a single planning artifact. It is intended for long-term product and engineering decisions—not as a runbook and not as a substitute for phase checklists.

Source-of-Truth Hierarchy (when docs conflict)

Delivery status: docs/progress.md (completed work) + docs/next-steps.md (immediate milestone) + docs/roadmap.md (future only)
Module inventory: docs/module-registry.md
Architecture intent: docs/architecture/* and ADRs
Contracts / schema: docs/reference/*
Historical inventory review: docs/current-architecture-review.md (dated 2026-07-22; some claims pre-date Accounting 5.x completion)

Explicit Conflicts Called Out in This Report

Topic	Side A	Side B	Preferred truth for this report
Accounting maturity	`database-architecture.md` still labels Accounting DB as “(future)”	`progress.md`, `module-registry.md`, Accounting phase area: Phases 5.1–5.11 complete, status Active	Active / implemented (registry + progress)
First business module	Product decision (Proposed): Restaurant after white-label	Accounting already delivered as Active business module	Accounting shipped; Restaurant remains preferred next go-to-market vertical after white-label polish (decision still Proposed)
Immediate next work	Older white-label narrative in some architecture notes	`next-steps.md`: Phase 5.12 AI readiness + production hardening	next-steps.md
Phase “3” meaning	External brief: onboarding as Phase 3	Internal: Phase 3 = OTP/Tenant Mgmt; Phase 4 = Onboarding	Internal numbering (`decisions/technical/phase-numbering.md`)
White-label completion	Framed as incomplete / next	Progress: partial runtime exists (`tenant-site`, theme, SSL)	Partial — polish still near-term
Message bus	Architecture describes outbox path	Real broker still future	Outbox/Celery today; bus later
Stale doc inventory claims	`current-architecture-review.md` (Jul 22): Identity real, business modules placeholders, Accounting not yet a delivered module	Jul 24 progress/scoreboard: Accounting backend + FE largely complete	Prefer Jul 24 progress/registry for Accounting; keep review file for historical doc-drift lessons

Reading Guide

Sections 1–3: executive and structural view
Sections 4–11: capability deep dives (modules, APIs, data, FE/BE, security, infra)
Sections 12–17: debt, refactoring, future platform map, scale, sequencing, recommendations, scorecard

1. Executive Summary

1.1 Current Project Maturity

TorbatYar is a multi-tenant SuperApp SaaS past foundation phases and into its first deep vertical: Accounting.

Stage	Status (per docs)
Phase 1 — Core Platform	Complete
Phase 2 — Identity & Access + SSO	Complete
Phase 3 — OTP + Tenant Management	Complete
Phase 4 — Onboarding & Workspace Activation	Complete (with intentional gaps)
Phase D — Documentation consolidation	Complete
Accounting 5.1–5.11	Complete (backend + enterprise FE baseline)
Accounting 5.12 AI	Blocked on AI Model Provider (Planned)
White-label runtime polish	Partial / near-term
Restaurant / CRM / commerce stack	Scaffolded or Planned

Maturity characterization: Platform core is production-shaped (Nginx edge, TLS, Keycloak SSO, tenant SSL automation, entitlement, onboarding). Business depth is strong in Accounting, thin elsewhere. Shared horizontal services (notification, file storage, SMS panel, payment, message bus) remain scaffolded/planned.

1.2 Current Architecture (one paragraph)

The system is service-oriented, API-first, database-per-service, row-level multi-tenant. A Next.js frontend talks only to versioned HTTP APIs. Nginx terminates TLS and routes apex/API/identity/auth/tenant hosts. Core Platform owns tenants, plans, entitlements, onboarding, audit, and outbox. Identity & Access is the OIDC BFF to Keycloak and owns identity profiles. Accounting is an independent service (accounting_db, port 8002 documented) with a sole Posting Engine for financial entries. Cross-service coupling is restricted to REST, webhooks, async events, and Outbox/Inbox. Celery workers process outbox and tenant SSL expansion.

1.3 Technology Stack

Layer	Technology (documented)
Frontend	Next.js 15.5.x, module routes, design system (`components/ds`), TanStack Query, Sonner, ColorMode
Backend services	Python services (Core, Identity, Accounting); layered API → Service → Repository → Model
Auth	Keycloak OIDC (RS256 JWT); Core OTP HS256 JWT; internal service tokens (hashed)
Data	PostgreSQL per service DB; Redis (entitlement cache, Celery broker usage implied by stack)
Workers	Celery worker + beat (outbox, SSL provision)
Edge	Nginx TLS, Let's Encrypt / Certbot, tenant SSL map + `provision_ssl.py`
Compose	postgres, redis, keycloak, core-service, identity-access-service, frontend, celery-worker, celery-beat
SMS	Payamak (Active)
Object storage / PSP / AI models	Planned

1.4 Overall Readiness

Dimension	Assessment
Multi-tenant SaaS foundation	Ready for early production tenants
Identity & workspace lifecycle	Ready (SSO + OTP + onboarding + JIT)
First enterprise vertical (Accounting)	Functionally broad; AI & some export/IAM depth remain
Horizontal platform services	Not ready (notification, files, payments, bus)
White-label / custom domain	Partial (subdomain SSL yes; DNS/TXT verify no)
100 / 1,000 / 10,000 tenants	See Enterprise Readiness — 100 plausible with ops discipline; 1k+ needs bus, isolation hardening, observability, horizontal scale

Verdict: Ready to operate and deepen Accounting, and to finish platform polish before proliferating many new business modules. Not yet ready as a full multi-vertical SuperApp marketplace.

1.5 Strengths

Clear ADR set (database-per-service, FE/BE split, tenancy, SSO, OTP, outbox, dual memberships, white-label, nginx SSL, posting engine).
Entitlement + membership dual-axis authorization model.
Tenant resolution order documented and operationally wired (headers → host → current tenant).
Accounting Posting Engine ownership prevents fragmented journals (ADR-010).
Documentation-as-software decision and consolidated docs/ tree after Phase D.
Production topology documented (app host + nginx edge + named public hosts).
Accounting FE scoreboard shows high completion across core financial screens (mostly 85–98%).
Shared-lib boundaries for JWT/events without owning domain workflows.

1.6 Weaknesses

Horizontal services delayed — notification, file storage, payment, real message bus.
White-label unfinished relative to product ambition for Restaurant guest sites.
Dual tenant_memberships increases cognitive and sync risk (ADR-007 accepted tradeoff).
Doc drift still present (e.g., Accounting marked future in database-architecture).
Advanced RBAC / invites not delivered.
Custom domain verification pending.
Observability is checklist-level (health endpoints + suggested alerts), not a full SRE stack in docs.
AI provider not Active → Accounting AI UI blocked at 0%.
Product decision for “first business module” out of sync with Accounting already shipping.

1.7 Biggest Risks

Risk	Why it matters	Mitigation direction
Adding many business modules before horizontal platform (files, notify, pay, bus)	Duplicated integrations, inconsistent UX, rewrite tax	Build shared platform services before 3rd+ vertical
Membership divergence Core vs Identity	Authz bugs / SSO listing mismatch	Explicit sync events or stricter ownership docs + tests
Tenant isolation regression as modules grow	Cross-tenant data leakage	Mandatory tenant denial tests per testing strategy
Outbox without real bus at scale	Throughput / fanout limits	Introduce broker without changing envelope (ADR-006 future)
Payment + subscription gaps	Cannot monetize or settle commerce	Provider + Core subscription path before marketplace
Doc staleness driving wrong builds	Teams implement against obsolete claims	Enforce progress/registry as status; fix architecture labels
Noise-neighbor DB at high tenant count	Row-level tenancy saturation	Partitioning / read replicas / eventual DB-per-large-tenant strategy

2. High Level Architecture

2.1 Architectural Style

Principle	Rule	ADR
Service-oriented	Major capabilities are independent services	Architecture overview
Database-per-service	One DB ownership per service; no cross-DB FK/joins	ADR-001
API-first	Versioned REST (+ events); UI never owns business rules	ADR-002
Multi-tenancy	`tenant_id` on business tables; no cross-tenant queries	ADR-003
Event reliability	Outbox/Inbox + `EventEnvelope`	ADR-006
Financial integrity	Only Accounting Posting Engine posts journals	ADR-010

2.2 Major Layers

flowchart TB
  subgraph Edge["Edge Layer"]
    NGX["Nginx TLS + Host Routing"]
  end
  subgraph Clients["Client Layer"]
    FE["Next.js Frontend<br/>SuperApp + Accounting module routes"]
  end
  subgraph Platform["Platform Services"]
    CORE["Core Platform<br/>tenants · plans · entitlement · onboarding · audit · outbox"]
    IDA["Identity & Access<br/>OIDC BFF · profiles · OTP handoff"]
    KC["Keycloak<br/>superapp realm · torbatyar theme"]
  end
  subgraph Business["Business Services"]
    ACC["Accounting<br/>COA · posting · GL · treasury · AR/AP · assets · payroll · reporting · compliance"]
    FUTURE["Scaffolded/Planned<br/>CRM · Restaurant · Ecommerce · …"]
  end
  subgraph Data["Data & Workers"]
    PG["PostgreSQL DBs per service"]
    RD["Redis"]
    CEL["Celery worker/beat"]
  end
  FE --> NGX
  NGX --> CORE
  NGX --> IDA
  NGX --> KC
  NGX --> ACC
  CORE --> PG
  IDA --> PG
  ACC --> PG
  CORE --> RD
  CORE --> CEL
  IDA --> KC
  ACC -.->|"entitlement check"| CORE
  FUTURE -.->|"API/events only"| CORE
  FUTURE -.->|"posting intents"| ACC

2.3 Dependency Flow

flowchart LR
  FE["Frontend"] --> CORE["Core API"]
  FE --> IDA["Identity API"]
  FE --> ACC["Accounting API"]
  FE --> KC["Keycloak"]
  IDA --> KC
  IDA --> CORE
  ACC --> CORE
  CORE --> PAYAMAK["Payamak SMS"]
  CORE --> SSL["Edge SSL provision via SSH"]
  CEL["Celery"] --> CORE
  CEL --> SSL

Allowed channels (integration architecture): versioned REST, webhook, async event, Outbox/Inbox.
Forbidden: cross-DB queries/FKs, importing another service’s models, frontend DB access, UI inventing journal entries.

2.4 Module Interaction (current vs planned)

sequenceDiagram
  participant U as User
  participant FE as Frontend
  participant KC as Keycloak
  participant ID as Identity
  participant C as Core
  participant A as Accounting
  U->>FE: Open /accounting
  FE->>KC: SSO (if needed)
  FE->>ID: token/me flows
  FE->>C: /me · tenant context · entitlement
  C-->>FE: tenant + roles
  FE->>A: API + Bearer + X-Tenant-ID
  A->>C: feature check (as required)
  A-->>FE: domain data
  Note over C: Outbox events for tenant/subscription lifecycle
  Note over A: voucher.posted / ledger.updated (catalog)

2.5 Runtime Topology (production canonical)

Component	Host / Endpoint
App / Docker	`192.168.10.162`
Nginx edge	`192.168.10.156`
Apex / tenant FE	`torbatyar.ir`, `*.torbatyar.ir`
Core API	`api.torbatyar.ir` → `:8000`
Identity API	`identity.torbatyar.ir` → `:8001`
Keycloak	`auth.torbatyar.ir` → `:8080`
Accounting API	Documented service port `:8002` (frontend `NEXT_PUBLIC_ACCOUNTING_API_URL`)

Compose services listed: postgres, redis, keycloak, core-service, identity-access-service, frontend, celery-worker, celery-beat. Accounting production deploy is called out as pending verification in next-steps.md.

2.6 Tenant Resolution & White-Label

Resolution order:

X-Tenant-ID
X-Tenant-Slug
Subdomain + PLATFORM_BASE_DOMAIN
Custom domain from Host
User current_tenant_id

Lifecycle: draft → pending_activation → active → suspended / archived (legacy inactive/deleted retained).

White-label: tenant brand fields + public tenant-site/theme by host; platform defaults from env/theme.config.json (ADR-008). Subdomain SSL expansion automated (ADR-009). Custom domain DNS/TXT verification not done.

3. Current Platform Capabilities

Capabilities below are grouped by domain using progress, module registry, provider registry, and frontend scoreboard. Items marked Planned/Scaffolded are listed as capabilities of the platform design, not as shipped product.

3.1 Core

Capability	Status
Project structure FE/BE separation	Done
Shared library (JWT, roles, events)	Done
Tenant CRUD / lifecycle	Done
Domains (subdomain provision)	Done
Plans / features / subscriptions seed (FREE/STARTER)	Done
Entitlement check + Redis cache	Done
Operational tenant memberships & roles	Done
Onboarding wizard APIs + services	Done
Public tenant-site resolution	Partial / present
Audit log	Done (architecture ownership)
Outbox/Inbox tables + worker path	Done (bus later)
Internal service tokens	Done
Service/module registry concept	Done (docs + Core ownership)
Payment gateway for subscriptions	Missing
DNS/TXT custom-domain verify	Missing
Legacy admin tenant auto membership/plan	Intentionally incomplete
Advanced permissions & invites	Missing
Independent Subscription service	Longer-term

3.2 Platform (Identity / Access / Edge)

Capability	Status
Keycloak realm/clients/theme	Done
Identity OIDC BFF	Done
Mobile OTP via Payamak (Core) + Identity handoff	Done
JIT Core user from Keycloak JWT	Done
Nginx reverse proxy + base TLS	Done
Automatic tenant subdomain SSL	Done
Cross-subdomain auth cookie model	Documented in review as operational concern
Rich Core↔Identity membership sync	Future

3.3 Business

Capability	Status
Accounting foundation → compliance (5.1–5.11)	Done
Accounting enterprise FE baseline	Done (AI blocked)
CRM	Scaffolded / not started
Restaurant / Cafe / Digital menu	Scaffolded / candidate
Ecommerce / Store builder	Scaffolded
Marketplace	Planned
Website / Landing builder	Scaffolded (`website_builder`)
Live Chat	Scaffolded
Smart Messenger	Scaffolded
Customer Club / Wallet	Not named as Active modules in registry (treat as future product capabilities)
Gym / Appointment / Reservation	Not dedicated Active modules in registry (Future/product)
ERP umbrella	Partially realized via Accounting depth; not a single ERP module

3.4 Infrastructure

Capability	Status
Docker Compose local/prod pattern	Done
Celery worker/beat	Done
Health endpoints Core/Identity	Done
Backup/restore/DR runbooks	Documented
Monitoring runbook (minimal alerts)	Documented
Real message bus	Missing
Full APM/metrics stack	Not evidenced as deployed in docs
CI/CD architecture deep doc	Historically called out as gap; branching/release strategies exist

3.5 Developer Experience

Capability	Status
Developer guides	Present
Coding standards / principles / testing strategy	Present
ADR system (001–010)	Present
Templates (module, phase, API, provider, ADR, decision)	Present
Module & provider registries	Present
Frontend design-system docs	Present
Phase docs for Accounting + area READMEs	Present
Documentation validation as phase exit	Required by testing strategy

4. Business Modules

Status legend from registry: Active · Scaffolded · Planned.

4.1 Accounting — Active

Field	Detail
Purpose	Tenant-aware double-entry accounting; sole Posting Engine; GL, treasury, AR/AP, sales/purchase/inventory accounting hooks, assets, payroll accounting, reporting, compliance/SoD
Current completion	Phases 5.1–5.11 complete; FE scoreboard mostly Complete (AI 0% Blocked); version `0.5.11.0`; migration `0002_phases_57_511`; 21 tests noted in progress
Implemented features	COA (4-level), fiscal year/period, currencies/FX, cost centers, projects/dimensions, voucher validate/post/reverse/cancel, ledger/trial balance, treasury, customers/suppliers AR/AP, sales integration, purchase/inventory valuation, fixed assets/depreciation, HCM/payroll posting, financial reporting/export framework, compliance/audit/governance
Missing features	Phase 5.12 AI UI (provider Planned); optional richer PDF export delivery; full tax authority connector; payment gateway; IAM rebuilt inside Accounting (deep-links only)
Dependencies	Core entitlement; ADR-010; shared JWT/tenant headers
Expansion capability	High within finance; must remain posting-engine-centric; AI only advisory

Accounting FE completion snapshot (2026-07-24)

Area	%	Gate
Dashboard	90	Complete
COA	98	Complete
Fiscal	98	Complete
Currencies	98	Complete
Cost Centers	95	Complete
Projects	95	Complete
Vouchers	95	Complete
Ledger	95	Complete
Treasury	90	Complete
Customers / AR	92	Complete
Suppliers / AP	85	Complete
Assets	90	Complete
Payroll	88	Complete
Reports	92	Complete
Compliance / Audit	88	Complete
Settings	85	Complete (IAM deep-links)
Setup	95	Complete
Mobile / Nav	90	Complete
AI	0	Blocked

4.2 CRM — Scaffolded

Field	Detail
Purpose	Customers, leads, opportunities, pipelines, tasks, automations
Completion	Not started (0.0.0)
Implemented	Placeholder service README / phase area only
Missing	Full domain, APIs, events, UI
Dependencies	Core entitlement; optional messenger/AI
Expansion	High; natural consumer of notification + AI

4.3 Restaurant / Cafe — Scaffolded (candidate GTM module)

Field	Detail
Purpose	Digital menu, tables, orders, kitchen, loyalty on tenant domains
Completion	Not started; product decision Proposed as preferred first vertical after white-label (note Accounting already exists)
Implemented	Scaffold only; conceptual `restaurant_db`
Missing	Menu, ordering, kitchen, loyalty, guest auth local to module DB, payments
Dependencies	Core entitlement, white-label host, optional Accounting postings via events, payment provider
Expansion	High for hospitality; depends on public site polish

4.4 Ecommerce — Scaffolded

Field	Detail
Purpose	Store builder, catalog, cart, orders, shipments
Completion	Not started
Missing	Entire commerce stack
Dependencies	Core, file_storage, payment, shipping
Expansion	Foundation for Marketplace

4.5 Marketplace — Planned

Field	Detail
Purpose	Multi-vendor market capabilities
Completion	Future
Dependencies	ecommerce, identity, accounting, payment
Expansion	Only after ecommerce foundation

4.6 Website Builder — Scaffolded

Field	Detail
Purpose	Sites, pages, blocks, forms, menus, media
Dependencies	file_storage / S3
Note	Ties into white-label public sites

4.7 Live Chat — Scaffolded

Field	Detail
Purpose	Embeddable widget, conversations, agent routing
Dependencies	Core; optional CRM/AI

4.8 AI Assistant — Scaffolded

Field	Detail
Purpose	Intelligent chat, KB, human handoff
Guardrail	Must not be authority for money, compliance, or authorization
Dependencies	AI model provider (Planned), Core entitlement

4.9 Smart Messenger — Scaffolded

Social channels, unified inbox, automations; depends on channel providers.

4.10 SMS Panel — Scaffolded

Campaign SMS separate from Core OTP path; multi-provider future.

4.11 Link Shortener — Scaffolded

Short links, custom domains, analytics; edge SSL for custom domains future.

4.12 Notification — Scaffolded (critical shared)

Central fanout email/SMS/push/webhook/in-app; should consume many domain events.

4.13 File Storage — Scaffolded (critical shared)

Tenant-aware uploads, S3 gateway, signed URLs planned.

4.14 Automation — Planned

Cross-module workflows; requires real message bus maturity.

4.15 Modules named in mission but not Active registry entries

The original master-report mission listed: Digital Menu, Customer Club, Wallet, Payment, Store/Website/Landing Builder, ERP, Gym, Workflow, Chat, Appointment, Reservation, Marketplace, AI, Automation.

Mapping from docs:

Mission name	Doc mapping
Digital Menu	Restaurant module
Customer Club	Not a dedicated Active module — future product on CRM/Restaurant/Wallet
Wallet / Payment	Payment Gateway provider Planned; no Active wallet module
Store Builder	Ecommerce
Website / Landing Builder	website_builder
ERP	Accounting depth + future modules; not single module
Gym	Not in registry — Future candidate
Workflow	Automation
Chat	live_chat (+ AI)
Appointment / Reservation	Not dedicated Active modules — Future/product
SMS Platform	sms_panel (+ Core OTP via Payamak)

5. Shared Platform Services

Reusable capabilities that multiple business modules should consume rather than reimplement.

5.1 Core Platform

Aspect	Assessment
Purpose	Tenant/plan/entitlement/onboarding/audit/outbox registry
Consumers	All services + Frontend
Quality	High relative maturity (Phases 1–4)
Missing	Payment, DNS verify, advanced RBAC/invites, subscription extraction
Recommendation	Harden production deploy + white-label; avoid stuffing business journals into Core
Priority	P0 continuous

5.2 Identity & Access

Aspect	Assessment
Purpose	SSO BFF, profiles, OTP handoff
Consumers	Frontend, all JWT services
Quality	Active and production-used
Missing	Richer sync with Core memberships
Recommendation	Define membership sync events before many staff UIs diverge
Priority	P0

5.3 Keycloak (IdP provider)

Aspect	Assessment
Purpose	Central staff SSO
Consumers	Identity, Frontend, JWT validators
Quality	Active
Missing	Operational runbooks beyond architecture notes (partially in deployment)
Recommendation	Treat as Tier-0 dependency; monitor availability
Priority	P0

5.4 Entitlement / Feature Gate (in Core)

Aspect	Assessment
Purpose	Plan-based feature access
Consumers	Accounting now; all future modules
Quality	Implemented with Redis cache
Missing	Independent subscription service (longer-term)
Recommendation	Keep stable feature key taxonomy `{service}.{resource}.{action}`
Priority	P0

5.5 Outbox / Event Backbone

Aspect	Assessment
Purpose	Reliable domain events
Consumers	Future notification, accounting integrations, automation
Quality	Pattern implemented; broker not real yet
Missing	Message bus, broader consumer ecosystem
Recommendation	Introduce bus before Automation engine
Priority	P1 before multi-module fanout

5.6 Notification (scaffolded)

Aspect	Assessment
Purpose	Central delivery
Consumers	All business modules
Quality	Scaffold only
Missing	Everything
Recommendation	Build before CRM/Restaurant campaigns
Priority	P1

5.7 File Storage (scaffolded)

Aspect	Assessment
Purpose	Tenant media/documents
Consumers	website_builder, ecommerce, accounting exports, KYC/assets docs
Quality	Scaffold; S3 provider Planned
Recommendation	Activate S3 provider + signed URL pattern early
Priority	P1

5.8 SMS Panel vs Core OTP

Aspect	Assessment
Purpose	Marketing/ops SMS vs auth OTP
Quality	OTP Active via Payamak; panel scaffolded
Recommendation	Keep OTP path separate; panel multi-provider later
Priority	P2 for panel; P0 for OTP reliability

5.9 Payment Gateway (planned provider)

Aspect	Assessment
Purpose	Subscriptions + commerce + restaurant pay
Missing	Provider selection and adapters
Recommendation	Required before Marketplace and paid plans automation
Priority	P1

5.10 AI Model Provider (planned)

Aspect	Assessment
Purpose	Assistants / Accounting 5.12
Status	Planned → blocks AI UI
Recommendation	Mark Active only with adapters + entitlement + non-authority guards
Priority	P1 for 5.12; P2 for broad AI

5.11 Shared Library

Aspect	Assessment
Purpose	JWT helpers, phone normalize, event envelope, shared errors
Quality	Foundational
Recommendation	Keep free of business workflows
Priority	P0

5.12 Edge SSL Provisioning

Aspect	Assessment
Purpose	Tenant HTTPS at scale
Quality	Automated via Celery→SSH→provision_ssl
Risk	Worker must reach nginx host; LE rate limits
Priority	P0 ops

6. API Platform

6.1 Overall API Quality

The platform is explicitly API-first. Core and Identity contracts live under docs/reference/services-contracts.md with an API index in api-reference.md. Accounting exposes versioned /api/v1 areas for foundation, posting, ledger, treasury, AR/AP, assets, payroll, reporting, and compliance. Frontend typed clients call real endpoints (Accounting client documented as no-mocks).

Quality posture: Strong conventions and versioning intent; consistency depends on each service following the same layering and error patterns. Historical review noted incomplete Identity README tables vs contracts—contracts should remain canonical.

6.2 Consistency

Expected convention	Documented practice
Prefix	`/api/v1` per service
Auth header	`Authorization: Bearer <token>`
Tenant header	`X-Tenant-ID` (and slug/host resolution)
DTOs	Pydantic schemas at API boundary
Feature keys	`{service}.{resource}.{action}`
Events	`{aggregate}.{past_tense_verb}` + EventEnvelope

Gaps: Dual frontend client naming historically (api.ts vs api-client.ts) called out in architecture review—document or consolidate. New modules must not invent alternate auth/tenant schemes.

6.3 Versioning

APIs are organized under api/v1/. Architecture requires versioned REST. No separate public v2 strategy is detailed yet—future breaking changes should add v2 rather than silently break v1 consumers (Frontend + future partners).

6.4 Security

Configurable AUTH_REQUIRED on Core
Role dependencies: authenticated, platform_admin, tenant_admin, membership role ensures
Accounting UI gated by AuthGuard + tenant id
Internal service tokens scoped; hashed at rest
Public tenant-site limited to public theme/site reads

6.5 Validation

Service architecture forbids business rules in routers but requires validation/HTTP mapping there. Accounting flows emphasize validate-before-post for vouchers. Testing strategy requires API contract tests including authz status codes.

6.6 Performance

Documented hot path: entitlement checks cached in Redis. Performance testing called out for entitlement/resolve paths “as needed.” No published SLA/latency budgets in the reviewed docs—treat as UNKNOWN beyond caching intent.

6.7 Future Readiness

Need	Readiness
Many module UIs on same auth	Ready (SSO JWT)
Event-driven integrations	Pattern ready; bus not ready
External partner APIs	Needs stronger public API program (not fully specified)
Webhooks as product	Allowed channel; productized webhook platform not Active

7. Database

7.1 Overall Schema Quality

Pattern: Database-per-service with UUID IDs and timezone-aware timestamps. Core and Identity schemas are documented; Accounting has migrations through 0002_phases_57_511. Future service schemas remain conceptual until migrations exist.

Conflict: database-architecture.md still lists Accounting as “(future)” while registry/progress mark it Active—update that architecture label.

7.2 Scalability

Row-level multi-tenancy (ADR-003) optimizes early ops (one DB per service). Architecture acknowledges noise-neighbor risk at very large scale; mitigation is future (partitioning / isolation strategies)—not implemented as a current project phase.

7.3 Tenant Readiness

Rule	Status
`tenant_id` on business tables	Required
No cross-tenant queries	Hard rule
Tenant denial tests	Required for new APIs
Platform admin cross-tenant support reads	Must be controlled + logged (compliance)

7.4 Relationships

No cross-DB foreign keys
Dual membership tables (ADR-007):
- core_platform_db.tenant_memberships — workspace authz source of truth
- identity_access_db.tenant_memberships — SSO listing
Accounting relationships remain inside accounting_db
Reference data duplication across services must sync via API/events

7.5 Performance

Indexes and query plans are not exhaustively published in architecture docs. Entitlement caching reduces repeated plan checks. Ledger recalculation and reporting are domain-heavy—capacity planning should treat them as scale hotspots when tenant count grows (engineering judgment labeled as planning recommendation derived from module scope, not a measured benchmark in docs).

7.6 Migration Strategy

Alembic per service
Never edit applied migrations in production
Historical ops caveat from architecture review: compose used upgrade 0001_initial && stamp head pattern—teams must understand stamp vs full upgrade risks
Accounting progress notes migration 0002_phases_57_511

8. Frontend

8.1 Architecture

Single Next.js SuperApp (not separate apps per module)
Accounting under app/accounting/** with AccountingShell
Strict FE/BE separation (ADR-002)
AuthGuard + /me + onboarding redirects
Design system tokens light/dark + components/ds
Catalog tile → /accounting

8.2 UI System

Documented design system, layout, navigation, tables, forms, dialogs, drawers, theme, responsive, accessibility docs under docs/frontend/. Accounting uses DS components and ColorModeProvider.

8.3 Routing

Module route placement under SuperApp. Platform routes include login/callback/dashboard/onboarding/tenant site paths (progress). Mobile nav polish marked Complete at 90% on scoreboard.

8.4 State Management

TanStack Query providers for server state; toasts via Sonner. Tenant via useTenantId / useMe. No indication that business writes bypass APIs.

8.5 Permission System

UI gated by roles from /me mirroring Core roles. Accounting settings IAM is deep-linked to SuperApp settings rather than rebuilt. Advanced permission trees still roadmap.

8.6 Reusable Components

Shared DS library intended for cross-module reuse. Frontend docs include component library and page/table/form patterns—good foundation for CRM/Restaurant UIs if enforced.

8.7 Scalability (FE)

Adding modules as route trees scales organizationally if:

Each module keeps its own API client
Shell/nav remains entitlement-aware
Bundle splitting discipline is maintained (performance doc exists; no numeric budgets extracted here)

White-label runtime polish remains a cross-cutting FE concern for public tenant hosts.

9. Backend

9.1 Architecture

Every backend service follows:

API (routers) → Services → Repositories → Models
                 ↑
              Schemas (DTOs)

Core layout includes core/, middlewares/ (tenant), workers/, api/v1/, tests/.

9.2 Modules

Service	DB	Status
core-platform	`core_platform_db`	Active
identity-access	`identity_access_db`	Active
accounting	`accounting_db`	Active 5.1–5.11
Others in registry	dedicated `*_db`	Scaffolded/Planned

9.3 Dependency Quality

Accounting → Core entitlement
Identity → Keycloak + Core OTP
Frontend → Core + Identity + Accounting + Keycloak
Business modules must not import each other’s models
Financial postings only via Accounting posting engine

9.4 Transaction Handling

Outbox pattern requires business row + outbox_events in one transaction. Accounting posting flows are transactional domain operations (validate/post/reverse/cancel). Cross-DB transactions are intentionally impossible—use eventual consistency via events.

9.5 Caching

Redis used for entitlement checks. Broader cache strategy for public tenant-site themes is implied by white-label architecture (“must stay cacheable”) but not fully specified as a platform cache product.

9.6 Queues & Background Jobs

Celery worker/beat:

process_outbox_events
provision_domain_ssl / SSL expansion path
Future jobs should follow same worker model until bus exists

9.7 Health Monitoring

Documented health checks for Core and Identity; Frontend HTTP 200; Keycloak realm availability. Suggested alerts: restart loops, Postgres/Redis down, cert expiry < 14 days, OTP error spikes, outbox failed growth.

10. Security

10.1 Authentication

Surface	Mechanism
Staff (platform/tenant)	Keycloak OIDC JWT RS256
OTP users	HS256 JWT after SMS verify
Service-to-service	Internal tokens (scoped, hashed)
Public tenant site	Unauthenticated public reads only

Mobile number mandatory + OTP verified (ADR-005). Passwords only in Keycloak.

10.2 Authorization

Two axes must pass: role + entitlement. Core memberships are operational SoT. Identity memberships are listing-oriented.

10.3 Permissions

Feature keys namespaced per service. Accounting uses accounting.*, treasury.*, receivable.*, payable.*, sales_accounting.*. Advanced custom permission trees / invites: roadmap.

10.4 Secrets & Configuration

Secrets in environment / secret stores—never git. Brand values not hardcoded (ADR-008). Backup docs call out storing .env outside git.

10.5 Potential Risks

Dual membership divergence
SSH-based SSL provision surface (worker → nginx host)
OTP provider outage blocking login paths
Incomplete custom-domain verify → spoofing/ops risk if misissued
Cross-tenant bugs as module count grows
AI future risk of over-authority (explicitly forbidden by AI architecture)

11. Infrastructure

11.1 Docker

Compose-based local and production app host. Services listed in deployment architecture. Accounting container deploy called out in next-steps exit criteria.

11.2 Deployment

Two-host production model: app 192.168.10.162, edge 192.168.10.156. Public DNS names for apex, API, identity, auth, wildcard tenants. Runbooks under docs/deployment/.

11.3 CI/CD

Branching and release strategies exist under docs/development/. Earlier architecture review flagged CI/CD as poorly documented relative to Gitea remote existence. Treat CI maturity as partially documented—do not invent pipeline details not present in docs.

11.4 Monitoring

Health endpoints + log locations + suggested minimum alerts. Not a full metrics/tracing platform description.

11.5 Backups

pg_dump for core/identity (and Keycloak DB if separate); retain 7/4/3 suggested; verify restores; include certs/nginx maps; future file buckets.

11.6 Scaling

Vertical VPS-oriented today. Horizontal scale requires: stateless API replicas, Redis/Celery scaling, Postgres capacity, edge capacity, and eventually a real message bus. Tenant SSL automation must respect LE rate limits.

12. Technical Debt

Grouped by severity using conflicts, intentional incompletes, and architectural risks documented across progress/roadmap/review/architecture.

12.1 Critical

ID	Finding	Notes
C1	Tenant isolation must remain perfect as modules explode	Testing strategy requires denial cases; failure is a company-ending bug class
C2	Financial integrity depends on universal ADR-010 adherence	Any module writing journals directly breaks compliance story
C3	Production hardening for Accounting deploy still open in next-steps	PATCH/setup/template import verification pending

12.2 High

ID	Finding	Notes
H1	No real message bus yet	Blocks Automation; limits fanout
H2	Notification & File Storage not built	Will be reimplemented ad hoc if modules proceed
H3	Payment gateway missing	Blocks monetization & commerce
H4	Custom domain DNS/TXT verification missing	White-label enterprise expectation
H5	Dual membership sync incomplete	ADR-007 accepted but unfinished operationally
H6	Doc drift (Accounting “future” in DB architecture; older review claims)	Misleads planning
H7	Advanced RBAC/invites missing	Enterprise tenant admin UX gap

12.3 Medium

ID	Finding	Notes
M1	White-label runtime partial	Near-term roadmap item
M2	AI provider Planned blocks 5.12	Scoreboard 0%
M3	Observability minimal	Suggested alerts not a full SRE stack
M4	Frontend API client dual naming history	DX confusion
M5	Legacy admin tenant auto provision incomplete	Tracked intentionally
M6	PDF export file delivery optional gap	Accounting FE remaining
M7	Product decision “first module = Restaurant” stale vs Accounting shipped	Update decision status

12.4 Low

ID	Finding	Notes
L1	Phase numbering alias confusion (external vs internal)	Glossary/decision exists—keep linking
L2	Placeholder service READMEs easy to misread as implemented	Registry status must be checked
L3	Independent Subscription service deferred	Acceptable mid-term
L4	Tax authority connector deferred	Explicitly out of early accounting scope

13. Refactoring Roadmap

Work that should happen before proliferating new business modules (CRM + Restaurant + Ecommerce simultaneously). Rationale: shared platform leverage and isolation safety.

13.1 Before next vertical (ordered)

#	Item	Why	Impact
1	Finish white-label public tenant runtime polish	Restaurant/digital menu depends on host branding/public paths	Unblocks hospitality GTM
2	Production-verify Accounting + FE	Avoid building on unstable prod baseline	Reduces incident risk
3	Reconcile stale architecture labels & product decision docs	Prevent wrong sequencing	Low code, high clarity
4	Membership sync strategy (events/tests)	Every new staff UI multiplies divergence risk	Prevents authz incidents
5	Activate File Storage + S3 provider	Media/docs needed by site/commerce/accounting exports	Avoids local disk hacks
6	Stand up Notification service MVP	Stops per-module SMS/email forks	Platform consistency
7	Payment provider adapter + subscription hooks	Monetization & restaurant/ecommerce pay	Revenue path
8	Message bus behind existing outbox	Enables Automation and scale fanout	Architectural unlock
9	Custom domain verification	Enterprise white-label completeness	Sales enablement
10	Advanced invites/RBAC	Multi-user tenants beyond owner	Enterprise readiness

Estimate (planning, not a formal quote): Items 1–4 are near-term hardening (days–few weeks of focused work depending on team size). Items 5–8 are multi-sprint platform investments. Items 9–10 are product-facing platform features.

13.2 Explicitly do not refactor away

Database-per-service
Outbox envelope
Keycloak central SSO for staff
ADR-010 posting ownership
Row-level tenant_id model (until scale evidence demands more)

14. Future Platform Architecture

Target structure to support the SuperApp portfolio.

14.1 Core Services

Service	Role
Core Platform	Tenants, domains, plans, entitlement, onboarding, audit, registries, internal tokens
Identity & Access	SSO BFF, profiles, OTP handoff
Keycloak	IdP
(Future) Subscription & Entitlement service	Extract when billing complexity demands

14.2 Shared Platform Services

Service	Role
Notification	Multi-channel fanout
File Storage	Tenant objects / signed URLs
SMS Panel	Campaign SMS (not auth OTP)
Payment	PSP adapters, webhooks
Link Shortener	Campaign links
Event Bus + Outbox workers	Reliable integration spine
Automation / Workflow engine	Cross-module triggers/actions
AI Assistant (platform)	Advisory only; provider-agnostic
Wallet (future)	Stored value / credits — should sit near Payment, not inside random verticals
Chat platform (live_chat)	Widget + routing shared by CRM/support

14.3 Business Modules

Module	Notes
Accounting / ERP financials	Already Active; posting hub for money
CRM + Customer Club features	Club can start as CRM segment/loyalty entities
Restaurant / Cafe / Digital Menu	Guest ordering on tenant domain
Appointment / Reservation / Gym	Vertical packs—prefer shared scheduling kernel later if multiple verticals need it
Ecommerce Store Builder	Catalog/cart/orders
Website / Landing Builder	Public content
Marketplace	After ecommerce + payment + identity maturity
Smart Messenger	Channel inbox

14.4 Infrastructure

Capability	Notes
Nginx edge + auto SSL	Keep; watch rate limits
Postgres per service	Keep; plan replicas/partitioning
Redis	Cache + queues
Celery → evolve with bus	Keep outbox ownership
Observability stack	Elevate from health checks to metrics/tracing/alerting productization
Backup/DR	Execute runbooks on schedule
CI/CD	Make pipelines first-class documented

14.5 Placement Map for Mission Capabilities

flowchart TB
  subgraph CoreSvc["Core Services"]
    CORE["Core Platform"]
    ID["Identity"]
    KC["Keycloak"]
    SUB["Subscription service future"]
  end
  subgraph Shared["Shared Platform Services"]
    NOTIF["Notification"]
    FILE["File Storage"]
    PAY["Payment"]
    SMS["SMS Panel"]
    BUS["Message Bus"]
    AUTO["Automation/Workflow"]
    AI["AI Assistant"]
    CHAT["Live Chat"]
    WALL["Wallet future"]
  end
  subgraph Biz["Business Modules"]
    ACC["Accounting/ERP finance"]
    CRM["CRM + Customer Club"]
    REST["Restaurant/Cafe/Menu"]
    ECOM["Store Builder"]
    WEB["Website/Landing Builder"]
    MKT["Marketplace"]
    GYM["Gym/Appointment/Reservation"]
  end
  Biz --> CoreSvc
  Biz --> Shared
  REST --> PAY
  ECOM --> PAY
  MKT --> ECOM
  ACC --> NOTIF
  CRM --> NOTIF
  WEB --> FILE
  ECOM --> FILE
  AUTO --> BUS

15. Enterprise Readiness

15.1 100 Tenants

Assessment: Achievable with current architecture if ops discipline holds.

Area	Bottleneck risk
Postgres row-level tenancy	Low–moderate
Nginx + SSL expand	Moderate (LE limits, SSH automation)
Keycloak	Low if sized
Celery outbox	Low–moderate
Support/observability	Medium (process)
Accounting heavy reports	Medium per active finance tenants

15.2 1,000 Tenants

Assessment: Conditional — needs platform upgrades.

Bottleneck	Why
Outbox without bus	Fanout to notification/CRM will choke
Single Postgres per busy service	Noise-neighbor / IO
Edge cert automation	Operational load
Redis/Celery capacity	Must be sized and monitored
Absence of Notification/File platforms	Ad hoc load on Core
RBAC/invites	Support burden multiplies
Custom domains	Verification + SSL complexity

15.3 10,000 Tenants

Assessment: Not ready on documented footing.

Required before serious pursuit:

Horizontally scaled APIs and workers
Real message bus + consumer autoscaling
DB strategy beyond naive shared tables (partitioning, replicas, possibly large-tenant isolation)
Mature multi-provider SMS/email/push
Payment + subscription systems hardened
Full observability and on-call
Self-service domain/SSL with rate-limit governance
Strong tenant isolation testing in CI
Possibly regional deployment (not documented today)

16. Recommended Development Order

Dependency-aware sequence synthesizing roadmap, next-steps, registries, and platform needs.

16.1 Wave 0 — Stabilize (now)

Accounting production deploy verification
Provider AI Active → Phase 5.12 (optional parallel)
Doc reconciliation (DB architecture Accounting status; product first-module decision)
White-label polish completion

16.2 Wave 1 — Shared platforms

File Storage + S3 provider
Notification MVP
Payment gateway provider
Custom domain DNS/TXT verify
Membership sync Core↔Identity
Message bus behind outbox

16.3 Wave 2 — GTM verticals

Restaurant / Digital Menu (depends on white-label + payment)
CRM (depends on notification; feeds Customer Club)
Customer Club / loyalty features (on CRM and/or Restaurant)

16.4 Wave 3 — Builders & content

Website / Landing Builder (depends on file storage)
Ecommerce / Store Builder (depends on file storage + payment)
Link Shortener / SMS Panel campaigns

16.5 Wave 4 — Conversational & AI

Live Chat
AI Assistant (provider-agnostic; never money authority)
Smart Messenger

16.6 Wave 5 — Platforms of platforms

Automation / Workflow (requires bus)
Wallet (requires payment)
Appointment / Reservation / Gym packs (prefer shared scheduling once ≥2 verticals need it)
Marketplace (requires ecommerce + payment + identity maturity + accounting settlement events)
Subscription & Entitlement independent service
Compliance connectors (tax authority)

16.7 Dependency Diagram

flowchart TD
  WL[White-label polish] --> REST[Restaurant/Menu]
  PAY[Payment] --> REST
  PAY --> ECOM[Ecommerce]
  FILE[File Storage] --> WEB[Website Builder]
  FILE --> ECOM
  NOTIF[Notification] --> CRM[CRM]
  BUS[Message Bus] --> AUTO[Automation]
  ECOM --> MKT[Marketplace]
  PAY --> MKT
  ID[Identity maturity] --> MKT
  ACC[Accounting] --> MKT
  AIProv[AI Provider] --> AI[AI Assistant]
  AI --> CHAT[Live Chat assist]
  CRM --> CLUB[Customer Club]
  REST --> CLUB

17. Final Architecture Recommendations

17.1 Immediate Actions

Execute next-steps.md exit criteria (AI provider decision, Accounting prod verify, scoreboard 5.12 unblock path)
Complete white-label runtime rendering gaps
Fix stale “Accounting (future)” labeling in database architecture docs
Update product decision: Accounting is Active; Restaurant is next hospitality vertical candidate
Enforce ADR-010 in all new module designs
Add/keep cross-tenant denial tests for every new tenant API
Monitor outbox failed growth + cert expiry

17.2 Next Phase

File Storage + S3 Active
Notification service MVP consuming core/accounting events
Payment gateway Active for subscriptions/commerce
Custom domain verification
Core↔Identity membership sync events
Introduce real message bus without breaking EventEnvelope
Advanced membership permissions & invites
Restaurant foundation after white-label+pay

17.3 Long-term Improvements

Automation engine
Marketplace
Independent Subscription service
Multi-region / higher-isolation tenancy options
Full observability (metrics, tracing, SLO dashboards)
Tax/compliance connectors
Shared scheduling kernel if Gym/Appointment/Reservation multiply
Wallet platform adjacent to Payment

18. Enterprise Scorecard

Scores are documentation-grounded judgments of current readiness (1 = absent/unfit, 10 = enterprise-proven at scale). They are not load-test results.

Dimension	Score	Rationale
Architecture	8	Clear ADRs, boundaries, layering; some doc drift
Modularity	8	DB-per-service + registries; many modules still scaffolds
Scalability	5	Fine for early SaaS; 1k–10k needs bus/DB/edge upgrades
Maintainability	7	Docs/ADR/phase discipline strong; dual memberships & drift cost
Security	7	SSO/OTP/tokens/TLS solid; RBAC depth & domain verify gaps
Backend	8	Core/Identity/Accounting real with layering; workers present
Frontend	7	SuperApp + DS + Accounting high completion; white-label partial
Database	7	Sound rules; Accounting label stale; scale strategy nascent
API	7	Versioned, tenant-aware; consistency/tooling still maturing
Testing	6	Strategy clear; Accounting 21 tests noted; not full enterprise matrix evidenced
Documentation	8	Post Phase D strong; conflicts remain in places
Developer Experience	7	Guides/templates/registries; dual clients & stubs confuse
Infrastructure	6	Compose+nginx+SSL real; monitoring/CI depth limited in docs
Enterprise SaaS Readiness	6	Strong foundation + one deep vertical; shared platforms incomplete

Scorecard summary chart

%%{init: {'theme': 'base'}}%%
quadrantChart
  title Readiness vs Strategic Importance
  x-axis Low readiness --> High readiness
  y-axis Lower leverage --> Higher leverage
  quadrant-1 Scale next
  quadrant-2 Protect & polish
  quadrant-3 Later
  quadrant-4 Foundation bets
  Architecture: [0.78, 0.85]
  Accounting: [0.82, 0.80]
  Identity: [0.80, 0.88]
  WhiteLabel: [0.55, 0.75]
  Notification: [0.20, 0.80]
  FileStorage: [0.20, 0.78]
  Payment: [0.15, 0.85]
  MessageBus: [0.25, 0.90]
  Restaurant: [0.15, 0.70]
  Marketplace: [0.05, 0.55]

Appendix A — ADR Index

ADR	Title	Status
ADR-001	Database-per-Service	Accepted
ADR-002	Strict Frontend / Backend Separation	Accepted
ADR-003	Row-Level Multi-Tenancy with tenant_id	Accepted
ADR-004	Central SSO with Keycloak	Accepted
ADR-005	Mandatory Mobile Identity with OTP	Accepted
ADR-006	Transactional Outbox / Inbox for Events	Accepted
ADR-007	Dual Tenant Membership Tables	Accepted
ADR-008	White-Label Branding via Config and Tenant Profile	Accepted
ADR-009	Nginx Edge with Automatic Tenant SSL Expansion	Accepted
ADR-010	Posting Engine Ownership for Accounting Entries	Accepted

Appendix B — Provider Status Snapshot

Provider	Status
Payamak	Active
Keycloak	Active
Let's Encrypt / Certbot	Active
S3-Compatible	Planned
Payment Gateway	Planned
AI Model Provider	Planned

Appendix C — Phase Numbering Glossary

Internal	Meaning
Phase 1	Core Platform
Phase 2	Identity & Access + SSO
Phase 3	OTP Login + Tenant Management
Phase 4	Tenant Onboarding & Workspace Activation
Phase D	Documentation Architecture Consolidation
Phase 5.x	Accounting module phases
External brief “Phase 3”	Often means onboarding → internal Phase 4

Appendix D — Event Catalog Snapshot (Core / Identity / Accounting samples)

Core: tenant.created, tenant.suspended, tenant.activated, domain.created, subscription.created, subscription.updated, feature_access.changed

Identity: user.registered, tenant_member.added, tenant_member.removed

Accounting (registry): voucher.posted, ledger.updated, cash.received, settlement.completed, sales_invoice.posted

Reserved future examples: CRM lead.* / opportunity.*; Restaurant order.*; Ecommerce order.* / product.*; Notification notification.delivered

Appendix E — Intentional Incompletes After Phase 4 (still open)

From progress:

Real payment gateway
Real DNS/TXT custom-domain verification
Membership/plan auto-provision on legacy POST /admin/tenants
First hospitality business module (Restaurant)—note Accounting later became the first deep vertical
Advanced permissions / invites
Independent Subscription service
Real message bus

Appendix F — Source Document Index Used for Synthesis

docs/progress.md, docs/roadmap.md, docs/next-steps.md, docs/last_step.md (if present), docs/module-registry.md, docs/provider-registry.md, docs/glossary.md
docs/current-architecture-review.md
docs/architecture/*, docs/architecture/adr/*
docs/reference/*
docs/deployment/*
docs/development/* (principles, testing, etc.)
docs/frontend/* (architecture + completion scoreboard)
docs/phases/**/README.md and Accounting phase area
docs/decisions/product/first-business-module.md, phase-numbering decision

Not used: application source code (per mission constraint for this master report generation pass).

Appendix G — Narrative Architecture Brief (extended)

TorbatYar’s strategic bet is that a SuperApp can share identity, tenancy, entitlement, edge TLS, and eventing, while each vertical owns its database and domain API. That bet is already partially validated: Core + Identity + edge SSL support real onboarding and host-based tenants; Accounting proves a deep vertical can live beside the platform without collapsing into a monolith—provided posting ownership and entitlement checks remain sacred.

The primary failure mode for the next 12–24 months is not “wrong framework choice.” It is premature module sprawl: scaffolding CRM, Restaurant, Ecommerce, Chat, and Messenger in parallel without Notification, File Storage, Payment, and a real bus. That path recreates N SMS integrations, N upload hacks, and N inconsistent authz bugs.

The primary success path is sequenced: harden platform polish → ship shared services → open verticals in dependency order → only then marketplace/automation at scale. Accounting should remain the financial spine; AI must remain advisory; guest experiences may use local auth inside vertical DBs without weakening staff SSO.

Operationally, the two-host VPS topology is appropriate for early production and ~100 tenants with discipline. Crossing into thousands of tenants is an infrastructure program, not a feature sprint.

Appendix H — Module Expansion Playbooks (summary)

H.1 Adding a business module

Create backend/services/<name>/ + DB + Alembic
Register in Core + module-registry.md
Feature keys + entitlement wiring
Events in catalog + outbox producers
Frontend module routes using DS + typed client
Tenant denial tests + docs/phase updates first if boundaries change

H.2 Adding a provider

provider-registry.md entry
Adapter boundary (no domain hardcode)
provider-reference.md ops sheet when Active
Tests for failure modes
Never mark Active without config + ownership

H.3 Touching money

Emit posting intent / use Accounting APIs
Never write JournalEntry lines in foreign modules
Keep audit metadata tenant-scoped

Appendix I — Risk Register (consolidated)

Risk	Likelihood	Impact	Owner lens	Treatment
Cross-tenant leak	Med if rushed	Critical	Every module	Mandatory tests + review
Journal fragmentation	Med without ADR education	Critical	Accounting + platform	ADR-010 gates
Busless fanout collapse	High as modules grow	High	Platform	Bus before Automation
Membership drift	Med	High	Identity + Core	Sync events
LE rate limit / SSL ops	Med	High	Ops	Throttle + monitoring
Doc-driven wrong build	Med	Med	Architecture	SoT hierarchy
Payment delay	High	High	Product	Provider wave 1
AI overreach	Low if guarded	High	AI + Compliance	Architecture rules

Appendix J — Readiness Checklist for “Open Next Vertical”

White-label public paths accepted by product
Entitlement keys reserved in registry
File upload story decided (File Storage or explicit exception)
Notification story decided
Payment needed? If yes, provider Active
Accounting impact? If yes, posting contracts defined
Guest auth decision (local vs SSO) documented
Phase docs created under docs/phases/
Scoreboard/progress hooks agreed

Appendix K — Glossary Essentials

Tenant: workspace/organization
Entitlement: plan feature gate
Posting Engine: only writer of accounting journals
Outbox/Inbox: reliable event publish/consume
JIT: just-in-time Core user link/create from Keycloak JWT
Platform admin: cross-tenant operator role
Tenant owner: required steward of an active workspace

Appendix L — Closing Statement

TorbatYar is past the “empty platform” stage. It has a coherent multi-tenant architecture, a working identity edge, and a serious Accounting vertical. Enterprise ambition is credible if shared platform services and operational scale work are sequenced ahead of SuperApp breadth. This master report should be treated as the planning baseline for that sequencing; update it when progress.md / registries change materially.

End of Master Architecture Report v1.0 — 2026-07-24

Appendix M — Accounting Phase Deep Dive (5.1–5.11)

This appendix expands Business Module Accounting using phase documents. All phases below are marked Complete in phase docs unless noted.

M.1 Phase 5.1 — Accounting Foundation (v0.5.1.0)

Delivered: Chart of Accounts, Account, Currency, Exchange Rate, Fiscal Year/Period, Cost Center, Project, Dimension, Accounting Settings, Document Number Sequence, Tenant Accounting Configuration; full Repository/Service/Schema/API layering; foundation events; accounting.* permissions; Alembic 0001_initial; tenant isolation tests.

API: /api/v1/accounts, /api/v1/fiscal

Architectural significance: Establishes the dimensional and fiscal spine every later financial feature depends on. Without open periods, active accounts, and tenant configuration, posting cannot be safe.

M.2 Phase 5.2 — Double Entry & Posting Engine (v0.5.2.0)

Delivered: Voucher, VoucherLine, Journal, JournalEntry; PostingEngine as sole creator of journal entries (ADR-010); validation for balanced entries, active accounts, open period; lifecycle Draft → Validated → Posted → Cancelled/Reversed; PostingLog/Error/Reference; AccountingAuditLog; APIs for validate/post/reverse/cancel/audit; permissions accounting.post, accounting.validate, accounting.reverse, etc.; events including voucher.posted, posting.completed, journal_entry.created.

Architectural significance: This is the compliance and integrity choke point for the entire SuperApp money path. Every future Restaurant/Ecommerce settlement must aim here, not invent ledgers.

M.3 Phase 5.3 — General Ledger & Fiscal Management

(Summarized from phase area completion and FE ledger capabilities.) Progress and FE architecture show ledger balances, trial balance, and recalculate against real /api/v1/ledger/*. Fiscal lock events appear in the event catalog (fiscal_period.locked, trial_balance.generated, ledger.updated).

Architectural significance: Turns posted vouchers into queryable financial truth for reports and period close.

M.4 Phase 5.4 — Treasury Management

FE scoreboard: Treasury 90% Complete — cash boxes, banks, bank accounts, cash receipts. Registry events include cash.received. Permissions include treasury.*.

Architectural significance: Bridges operational cash movement to posting; payment gateway later should settle into treasury/accounting flows rather than bypass them.

M.5 Phase 5.5 — Accounts Receivable & Payable

FE: Customers/AR 92%, Suppliers/AP 85%. Events include settlement.completed. Permission prefixes receivable.*, payable.*.

Architectural significance: Customer/supplier subledgers become integration points for CRM and commerce later—prefer references + events over duplicating party masters carelessly.

M.6 Phase 5.6 — Sales Accounting Integration

Events: sales_invoice.posted, revenue.recognized. Permission prefix sales_accounting.*.

Architectural significance: Pattern for “operational document → accounting posting intent → Posting Engine.” Ecommerce/Restaurant should copy this pattern.

M.7 Phase 5.7 — Purchase & Inventory Accounting Integration

Progress: InventoryValuationEngine delivered with migration 0002_phases_57_511 covering 5.7–5.11.

Architectural significance: Inventory valuation is a classic cross-module hazard; ownership stays in Accounting for valuation postings even if stock quantities later live in another service.

M.8 Phase 5.8 — Fixed Assets Management

FE Assets 90%: categories, activate, depreciate, schedule. DepreciationEngine noted in progress.

M.9 Phase 5.9 — HCM & Payroll Accounting

FE Payroll 88%: departments, periods, calculate, post. PayrollEngine noted in progress.

Architectural significance: Payroll is compliance-sensitive; AI must not become posting authority here.

M.10 Phase 5.10 — Financial Reporting & BI (v0.5.10.0)

Delivered: FinancialReport, ReportTemplate, Dashboard/Widget, KPI, ReportSnapshot, ScheduledReport, ReportExport, ReportHistory, ReportConfiguration; FinancialReportEngine for trial balance, balance sheet, income statement from posted data; export framework PDF/Excel/CSV/JSON; API /api/v1/reporting; permissions reports.*, dashboard.*, financial_statements.view; events financial_report.generated, balance_sheet.generated, report.exported.

Remaining (progress): optional richer PDF export file delivery from storage — depends on File Storage maturity.

M.11 Phase 5.11 — Enterprise Compliance, Audit & Governance (v0.5.11.0)

Delivered: immutable AuditRecord/History; CompliancePolicy; GovernanceRule; ApprovalWorkflow/Step/Request; Delegation; RiskRecord; PolicyViolation; Evidence; RetentionPolicy; ControlDefinition; AuditFramework, ComplianceEngine, GovernanceService (approvals, SoD, risk); API /api/v1/compliance; permissions audit.*, compliance.*, governance.*, approval.execute, risk.*; events audit_record.created, approval.completed, policy_violation.detected.

Conflict note: compliance-architecture.md still has a subsection titled “Accounting Compliance (future)” listing double-entry integrity and dimensions as future — but 5.2/5.11 phase docs mark substantial compliance machinery Complete. Prefer phase/progress for implementation status; treat the architecture subsection as needing wording refresh (tax connectors remain future).

M.12 Phase 5.12 — AI Native Accounting (planned / blocked)

Blocked until AI Model Provider is Active in provider registry. AI architecture forbids AI as sole authority for money/compliance/authorization. FE scoreboard AI = 0% Blocked.

Appendix N — Twenty Project Principles (operational translation)

#	Principle	Architecture implication
1	Tenant-aware everything	Middleware + repository filters + FE `X-Tenant-ID`
2	Auditable business actions	Core audit_logs + module audit/events
3	Logic in Services	Thin routers
4	Repositories persistence-only	No hidden workflows in ORM layer
5	Thin API handlers	Validate → authorize → service → map
6	Tests per phase	pytest per service; tenant denial cases
7	Docs per phase	registries/contracts/progress
8	No TODO in completed phases	TODOs reopen the phase
9	No cross-tenant query	Logged platform_admin exceptions only
10	No direct JournalEntry	ADR-010
11	Compliance independent	Controls survive UI redesign
12	AI independent	Product works with AI off
13	Event-ready	Outbox-backed effects
14	API-first	UI is a client
15	Everything documented	ADRs/registries current
16	Database-per-service	ADR-001
17	Absolute FE/BE split	ADR-002
18	No hardcoded brand/secrets	env/config/DB
19	Docs before conflicting code	stop-the-line
20	Phase completion gate	docs README checklist

Appendix O — Frontend Platform Standards (for all future modules)

Derived from docs/frontend/* index hard rules and architecture.

O.1 Hard Rules

Never mock accounting (or, by extension, other module) business data in enterprise screens.
Never bypass the owning service API.
Always send JWT + X-Tenant-ID.
Journal entries only via Posting Engine UI actions.
Reuse Design System — do not redesign per page.

O.2 Documented FE knowledge areas

Design system (tokens, typography, themes, RTL), component library, layout/shell, page patterns (dashboard/list/form/report), RHF+Zod forms, tables, dialogs, theme/white-label, navigation maps, responsive breakpoints, API integration, TanStack Query state, performance splitting, WCAG AA baseline, testing quality gates.

O.3 Implication for Restaurant/CRM UIs

New verticals should open as SuperApp module routes with DS components, Query providers, and entitlement-aware nav—not new Next apps—unless an ADR supersedes ADR-002’s deployment model.

Appendix P — Production & SSL Operations Digest

P.1 Hosts & public routing

Host	Upstream
`torbatyar.ir` / `www` / `*.torbatyar.ir`	Frontend `:3000`
`api.torbatyar.ir`	Core `:8000`
`identity.torbatyar.ir`	Identity `:8001`
`auth.torbatyar.ir`	Keycloak `:8080`
`accounting.torbatyar.ir`	Accounting `:8002`

App host 192.168.10.162; Nginx edge 192.168.10.156.

P.2 Deploy shape

Pull release on app host
docker compose up -d --build
Alembic per service (document stamp vs upgrade precisely in release notes)
Reload Nginx if routing changed
Smoke: /health, login, tenant subdomain

Critical env groups: PLATFORM_*, NEXT_PUBLIC_*, DB URLs, KEYCLOAK_*, AUTH_REQUIRED, Payamak/OTP, PLATFORM_ADMIN_MOBILES, SSL_PROVISION_*.

P.3 TLS

Edge terminates TLS with LE material under /etc/letsencrypt/live/torbatyar.ir/. Platform hosts force HTTPS; ACME on port 80. Tenant subdomain SSL via Celery SSH → provision_ssl.py when SSL_PROVISION_ENABLED=true; readiness map torbatyar-tenant-ssl.map. Custom domains may remain pending until DNS verification ships.

P.4 Backup & DR posture

Daily pg_dump of service DBs; retain 7 daily / 4 weekly / 3 monthly (suggested); restore drills; protect secrets, certs, nginx maps; future object storage buckets.

P.5 Monitoring minimum

Health endpoints; Docker/Nginx/Celery logs; alerts for restart loops, DB/Redis down, cert expiry < 14 days, OTP error spikes, outbox failed growth.

Appendix Q — Identity & Authorization Worked Examples

Frontend /login → Keycloak themed login (password or mobile OTP via Identity handoff) → /auth/callback → JWT in FE → Core /me / tenant context → module APIs with Bearer + tenant header.

Q.2 OTP path

Core OTP request/verify via Payamak → HS256 JWT → UserService.resolve_current maps to users.id. Identity delegates SMS to Core OTP client (no duplicate SMS logic).

Q.3 JIT path

Keycloak JWT → resolve/link via users.keycloak_sub (implemented; older contracts saying 403/deferred are stale).

Q.4 Authorization decision table

Check	Pass condition
Authentication	Valid JWT (Keycloak or OTP)
Workspace role	Core membership role sufficient for action
Entitlement	Plan/feature/custom override allows feature key
Tenant scope	Resolved tenant matches resource tenant
Posting	Accounting permissions + open period + balanced voucher

Q.5 Dual membership caution

Identity tenant_admin/tenant_member listing roles are not operational authz. UI and services must not authorize workspace mutations from Identity membership alone.

Appendix R — Eventing Blueprint for Future Modules

R.1 Envelope fields

event_id, event_type, aggregate_type, aggregate_id, tenant_id, source_service, payload, occurred_at.

R.2 Producer checklist

Write business change + outbox row atomically
Name event {aggregate}.{past_tense}
Update event catalog + module registry producers
Do not require synchronous cross-DB commit

R.3 Consumer checklist

Inbox insert by event_id (idempotent)
Handle payload in service layer
Emit follow-up events if needed
Never call foreign DB

R.4 Suggested future event families (reserved in catalog)

Module	Examples
CRM	`lead.created`, `opportunity.won`
Restaurant	`order.placed`, `order.completed`
Ecommerce	`order.placed`, `product.updated`
Notification	`notification.delivered`

Appendix S — Capability Matrix (Implemented vs Designed)

Capability	Implemented	Scaffold/Planned	Depends on
Multi-tenant workspaces	Yes		Core
SSO staff login	Yes		Keycloak/Identity
OTP mobile login	Yes		Payamak
Onboarding wizard	Yes		Core/FE
Subdomain SSL auto	Yes		Celery/Nginx/LE
Entitlement engine	Yes		Redis/Core
Accounting full 5.1–5.11	Yes	5.12 AI	Core
Accounting FE enterprise	Mostly	AI UI	Accounting API
White-label polish	Partial	Complete runtime	Public site
Custom domain verify		Yes	DNS
Payment		Yes	PSP
Notification hub		Yes	Bus helpful
File storage		Yes	S3
CRM		Yes	Core/Notify
Restaurant		Yes	White-label/Pay
Ecommerce		Yes	File/Pay
Marketplace		Yes	Ecommerce+
Live chat / AI / Messenger		Yes	Providers
Automation		Yes	Bus
Message bus		Yes	Infra

Appendix T — Target Operating Model for Enterprise SaaS

T.1 Team boundaries (recommended)

Team	Owns
Platform	Core, Identity edge contracts, entitlement, tenancy, edge SSL
FinTech/Accounting	Accounting service + posting contracts
Experience	SuperApp FE shells, DS, white-label
Growth verticals	Restaurant/CRM/Ecommerce module delivery
Ops	Compose, Nginx, backups, certs, alerts

T.2 Change control

Architecture/ADR update if boundaries change
Registry + contracts + events
Implementation + tests
Progress/scoreboard

T.3 Definition of Ready for a new module

Phase README created
DB name reserved
Feature key prefix reserved
Entitlement plan flags designed
Dependencies (file/notify/pay) explicit
FE route namespace reserved

T.4 Definition of Done

Aligns with principles 6–8, 15, 20: tests, docs, no TODO, registries updated, progress checked.

Appendix U — Scale Bottleneck Catalog (detailed)

U.1 Application layer

Bottleneck	100	1k	10k
API single-node	OK	Need replicas	Mandatory HA
Keycloak	OK	Size up	Cluster
Accounting report CPU	Watch	Isolate workers	Dedicated read models
FE SSR/hosting	OK	CDN/cache	Multi-node

U.2 Data layer

Bottleneck	100	1k	10k
Shared tenant rows	OK	Indexes/partition	Partition + large-tenant strategy
Backup windows	OK	Parallel dumps	Continuous/PITR
Cross-service sync lag	Low	Visible	Needs bus SLOs

U.3 Edge / certs

Bottleneck	100	1k	10k
LE SAN expansion	Manageable	Rate-limit risk	Different cert strategy likely
Nginx fanout	OK	Tune	Scale edge

U.4 Async

Bottleneck	100	1k	10k
Celery outbox poll	OK	Tune concurrency	Bus + partitioned consumers
Notification fanout without hub	Painful	Severe	Impossible cleanly

Appendix V — Prioritized Platform Backlog (architecture view)

P0

Production verify Accounting host routing (accounting.torbatyar.ir)
White-label completion
Doc conflict cleanup
Tenant isolation regression suite expansion

P1

File Storage + S3 Active
Notification MVP
Payment provider
Message bus
Custom domain verify
Membership sync
Invites/RBAC

P2

Restaurant foundation
CRM foundation
AI provider + 5.12
Website builder
SMS panel campaigns

P3

Ecommerce
Chat/Messenger
Automation
Marketplace
Wallet / Gym packs / scheduling kernel

Appendix W — Conflict Log (full)

ID	Conflict	Resolution used here
X1	DB architecture lists Accounting future	Accounting Active 5.11
X2	Compliance architecture “future” subsection vs 5.11 complete	Implementation complete; tax connectors still future
X3	Product decision first module Restaurant vs Accounting shipped	Accounting is first deep vertical; Restaurant next GTM candidate
X4	next-steps AI/prod vs roadmap near-term Restaurant/white-label	Both valid: next-steps = immediate; roadmap = near; do Wave 0 then white-label/Restaurant
X5	current-architecture-review (Jul 22) pre-Accounting depth	Historical for doc drift; not status SoT
X6	Phase 3 naming external vs internal	Internal numbering wins
X7	Older JIT deferred claims	JIT done
X8	Older nginx later claims	Nginx/TLS done
X9	services placeholder-only claims	Identity + Accounting real
X10	Event catalog “Accounting 5.1–5.6” heading while 5.7–5.11 exist	Catalog needs extension note; registry lists additional events

Appendix X — Recommendation Narratives

X.1 Why shared services before more verticals

Accounting already shows how deep a vertical can become. If Restaurant and CRM each implement uploads, SMS, and payments independently, the platform becomes a federation of accidental monoliths. Notification, File Storage, and Payment are force-multipliers: one hardening effort benefits all modules.

X.2 Why message bus before Automation

Automation without a durable fanout fabric will either poll databases unsafely or couple modules via brittle synchronous chains. ADR-006 already anticipates swapping publish transport without rewriting producers—use that escape hatch before building workflow product UX.

X.3 Why Restaurant still matters after Accounting

Accounting monetizes and operationalizes finance-heavy tenants. Restaurant/digital menu monetizes SMB hospitality on white-label domains—the original product wedge in the Proposed decision. They are complementary, not mutually exclusive; sequencing should still respect white-label and payment prerequisites.

X.4 Why AI is last among Accounting phases

Principle 12 and AI architecture require business continuity without AI. Shipping 5.12 before provider governance risks putting probabilistic systems near money. Keep AI advisory with human/approval gates (especially given 5.11 SoD tooling).

Appendix Y — Scorecard Narrative Detail

Architecture (8/10)

Strength from ADRs and boundaries; deducted for stale labels and incomplete horizontal architecture realization.

Modularity (8/10)

Physical module boundaries exist; many modules are empty shells—modularity of design exceeds modularity of delivery.

Scalability (5/10)

Appropriate early VPS SaaS; insufficient evidence/plan execution for 10k tenants.

Maintainability (7/10)

Docs+tests culture strong; dual membership and sprawl risk weigh down.

Security (7/10)

Solid authn/TLS/tenant rules; enterprise RBAC/domain verify incomplete.

Backend (8/10)

Three real services with clear layering and workers.

Frontend (7/10)

Strong Accounting module patterns and DS; white-label and multi-module nav still maturing.

Database (7/10)

Good rules and Accounting migrations; scale playbook thin; doc drift.

API (7/10)

Versioned and tenant-aware; ecosystem consistency still forming.

Testing (6/10)

Strategy excellent; breadth beyond cited suites not fully evidenced in status docs.

Documentation (8/10)

Phase D success; conflicts remain.

Developer Experience (7/10)

Templates/registries help; stubs and dual clients confuse.

Infrastructure (6/10)

Real edge/app split; observability/CI depth limited in docs.

Enterprise SaaS Readiness (6/10)

Credible mid-market start; not yet a diversified SuperApp at enterprise scale.

Appendix Z — Master Checklist Recap (printable)

Immediate

Accounting prod smoke on accounting.torbatyar.ir
White-label gaps closed
Stale docs reconciled
AI provider go/no-go recorded

Next

File Storage Active
Notification MVP
Payment Active
Bus introduced
Domain verify
Membership sync
Invites/RBAC

Later

Restaurant
CRM/Club
Builders
Chat/AI/Messenger
Automation
Marketplace
Wallet/Gym/scheduling

Appendix AA — Long-form Executive Briefing (for leadership)

TorbatYar set out to build a multi-tenant SuperApp that can host many business systems behind one identity and one entitlement plane. The organization has substantially delivered the platform kernel (Core, Identity, Keycloak, Nginx TLS, tenant SSL automation, onboarding) and has gone unusually deep on Accounting as a first enterprise vertical—including posting integrity, treasury, AR/AP, inventory accounting, assets, payroll accounting, reporting, and governance/SoD.

That combination is rare for early-stage platforms and should be treated as a strategic asset: the company can sell credible financial operations while the SuperApp shell continues to expand. However, leadership should not interpret Accounting depth as proof that the platform can absorb unlimited new verticals immediately. The missing middle—files, notifications, payments, and a real event bus—determines whether the next modules will compound or fragment.

Commercially, two motions can coexist:

Finance-led motion: land tenants needing accounting/compliance depth.
Hospitality-led motion: land cafes/restaurants on white-label digital menus once public-site polish and payments exist.

Technically, the non-negotiables remain tenant isolation, posting-engine exclusivity for money, API-first boundaries, and documentation-before-code when architecture shifts. Scaling from dozens to thousands of tenants is primarily an infrastructure and shared-services program. Scaling from one vertical to many is primarily a sequencing discipline.

This master report recommends Wave 0 hardening now, Wave 1 shared platforms next, then Restaurant/CRM, then builders and conversational systems, with Marketplace and Automation last among the major bets.

Appendix AB — Interface Contracts Overview (planning level)

Consumer	Provider	Contract theme
FE	Core	`/api/v1` tenants, onboarding, me/context, entitlement check, public tenant-site
FE	Identity	`/api/v1/auth` OIDC/mobile
FE	Accounting	`/api/v1/*` foundation→compliance
FE	Keycloak	OIDC browser flows
Identity	Core	OTP client
Accounting	Core	entitlement / tenant authenticity assumptions
Celery	Core domain	outbox publish, SSL provision
Future Notification	many	consume domain events
Future modules	Accounting	posting intents / settlement events

Detailed endpoint tables remain in docs/reference/services-contracts.md and api-reference.md (not duplicated exhaustively here to avoid a third competing contract source).

Appendix AC — Data Ownership Map

Data class	Owner DB
Tenant, plan, subscription, operational membership	`core_platform_db`
Identity profile, SSO membership listing	`identity_access_db`
COA, vouchers, journals, GL, treasury, AR/AP, assets, payroll acct, reports, compliance records	`accounting_db`
CRM entities	`crm_db` (future)
Restaurant menu/orders	`restaurant_db` (future)
Store catalog/cart	`ecommerce_db` (future)
Site pages/blocks	`website_builder_db` (future)
Chat transcripts	`live_chat_db` (future)
AI KB/sessions	`ai_assistant_db` (future)
Notifications	`notification_db` (future)
Files metadata	`file_storage_db` (future)

Appendix AD — Security Control Baseline

Control	Mechanism
Authn staff	Keycloak OIDC
Authn OTP	Payamak + Core JWT
Authz role	Core memberships
Authz feature	Entitlement service
Transport	TLS at edge
Secrets	env / vault, not git
Audit	Core audit_logs + accounting audit framework
Tenant isolation	tenant_id filters + tests
Service auth	hashed internal tokens + scopes
Money integrity	Posting Engine only
AI limitation	non-authority rule

Appendix AE — Open Questions (explicit UNKNOWN / pending decisions)

These items are not answered conclusively in the synthesized docs and should be decided deliberately:

Final Iranian PSP selection for Payment Gateway
Final AI model vendor(s)
Whether Customer Club is a CRM submodule, Restaurant loyalty, or standalone service
Whether Appointment/Gym share a scheduling kernel early or duplicate per vertical
When to extract Subscription/Entitlement from Core
Exact production Alembic procedure standardization (upgrade vs stamp discipline)
CI pipeline topology (documented strategies exist; full pipeline inventory not treated as complete in older review)
Whether Accounting public hostname is fully live in all environments (next-steps still asks for deploy verification)

End of expanded appendices — Master Architecture Report v1.0

Appendix AF — Accounting Phases 5.3–5.9 Detailed Deliverables

Source: individual phase markdown files under docs/phases/Accounting/.
Note: Phase 5.6 “Related” still links 5.7 as “(planned)” while 5.7 file Status is Complete — another small doc conflict; prefer Status fields.

AF.1 Phase 5.3 — General Ledger & Fiscal Management

Delivered entities/services: GeneralLedger, LedgerBalance, TrialBalanceSnapshot, BalanceSnapshot, OpeningEntry, ClosingEntry, AccountingCalendar; BalanceEngine (running balances, trial balance, recalculation); FiscalManagementService (lock/close/reopen periods, year closing).

API: Ledger balances, trial balance, recalculate.

Permissions: accounting.ledger.*, accounting.fiscal.*, accounting.trial_balance.view

Events: trial_balance.generated, ledger.updated, fiscal_period.locked, etc.

Enterprise note: Period lock is a control boundary; Automation/AI must never reopen periods without governance approvals (5.11 tooling).

AF.2 Phase 5.4 — Treasury Management

Delivered: CashBox, CashTransaction, Bank, BankAccount, BankTransaction, Cheque, ChequeBook, Transfer, ReceiptVoucher, PaymentVoucher, reconciliation framework, TreasurySettings; TreasuryService — cash receipt/payment via Posting Engine only.

Permissions: treasury.*

Events: cash.received, bank_deposit.created, cheque.issued, etc.

Enterprise note: Future Payment Gateway settlements should land as treasury/accounting postings, not orphaned PSP ledgers.

AF.3 Phase 5.5 — Accounts Receivable & Payable

Delivered: CustomerAccount, SupplierAccount, ReceivableInvoice, PayableInvoice, Settlement, SettlementAllocation, CreditNote, DebitNote, AdvancePayment, AdvanceReceipt, CustomerStatement, SupplierStatement, AgingSnapshot; SettlementEngine; AgingEngine.

Permissions: receivable.*, payable.*, settlement.manage

Events: customer_invoice.created, settlement.completed, etc.

Enterprise note: CRM should reference accounting party accounts carefully—prefer correlation IDs/events over dual-write of balances.

AF.4 Phase 5.6 — Sales Accounting Integration

Delivered: SalesPostingProfile, AccountingProfile, PostingRule, SalesAccountingConfiguration, RevenueRecognition, RevenueSchedule, AccountingPreview, PostingSimulation; SalesAccountingService preview + post via Posting Engine; configurable posting profiles per document type.

Permissions: sales_accounting.*

Events: sales_invoice.posted, revenue.recognized, posting_rule.executed, etc.

Pattern to copy: operational document → preview → post via engine.

AF.5 Phase 5.7 — Purchase & Inventory Accounting

Delivered: PurchasePostingProfile, InventoryPostingProfile, InventoryValuationMethodConfig, InventoryValuationHistory, InventoryCostAdjustment, InventorySnapshot; InventoryValuationEngine (FIFO, weighted/moving average); PurchaseInventoryAccountingService goods receipt via Posting Engine.

API: /api/v1/purchase-inventory

Permissions: purchase_accounting.*, inventory_accounting.*

Events: goods.received, inventory.adjusted, purchase_accounting.completed

AF.6 Phase 5.8 — Fixed Assets

Delivered: Asset register, categories, groups, locations; AssetDepreciation, DepreciationSchedule; AssetTransfer, Disposal, Revaluation, Impairment; AssetAccountingProfile, AssetHistory; DepreciationEngine (straight line, declining balance, double declining); AssetAccountingService activate/depreciate via Posting Engine.

API: /api/v1/assets · Permissions assets.* · Events asset.depreciated, depreciation.calculated, etc.

AF.7 Phase 5.9 — HCM & Payroll Accounting

Delivered: Employee, Department, Position, EmploymentContract; PayrollPeriod, Payroll, PayrollItem, SalaryComponent; Benefit, Allowance, Deduction, EmployeeLoan, EmployeeAdvance; PayrollAccountingProfile, PayrollHistory, PayrollSettlement; PayrollEngine; PayrollAccountingService posting via Posting Engine.

API: /api/v1/payroll · Permissions hr.*, payroll.* · Events payroll.calculated, payroll.posted, payroll_accounting.completed

Boundary caution: This is accounting-oriented HCM, not necessarily a full HRIS product. A future standalone HR module should integrate rather than fork payroll journals.

Appendix AG — Architecture Decision Records (digest)

AG.1 ADR-001 Database-per-Service

Decision: Every service owns exactly one database; cross-service access only via REST/Webhook/Async Event/Outbox-Inbox.

Why it matters: Prevents schema coupling as SuperApp grows.

Tradeoff: No cross-DB joins; eventual consistency required.

AG.2 ADR-002 Strict FE/BE Separation

Decision: Backend only under backend/, Frontend only under frontend/; communication via versioned APIs.

Why: Independent deploy/scale; multiple UIs possible.

AG.3 ADR-003 Row-Level Multi-Tenancy

Decision: Shared DB per service with mandatory tenant_id; resolution order headers→host→current tenant.

Tradeoff: Noise-neighbor risk at extreme scale.

AG.4 ADR-004 Central SSO Keycloak

Decision: Keycloak central login for platform/tenant staff; Identity is BFF; end-customer auth may be local to module DB.

AG.5 ADR-005 Mandatory Mobile + OTP

Decision: Mobile required and OTP-verified (Payamak).

AG.6 ADR-006 Outbox/Inbox

Decision: Business + outbox same transaction; inbox idempotency by event_id; envelope standardized.

Future: Swap to real bus without rewriting producers.

AG.7 ADR-007 Dual Membership Tables

Decision: Core memberships = operational SoT; Identity memberships = SSO listing.

Risk: Naming collision and divergence—must stay explicit in docs/tests.

AG.8 ADR-008 White-Label via Config/Profile

Decision: Platform defaults from env/theme config; tenant brand fields on tenants; FE CSS variables; public host theme resolution.

AG.9 ADR-009 Nginx + Auto Tenant SSL

Decision: Nginx TLS edge; LE expand via Celery SSH provision_ssl.py; SSL readiness map.

AG.10 ADR-010 Posting Engine Ownership

Decision: No service/UI creates JournalEntry directly; all financial postings through Accounting Posting Engine.

Consequence: Modules wait on Accounting contracts for money write-paths.

Appendix AH — Future Capability Placement Matrix (mission list)

Capability	Architectural placement	Status in docs	Purpose	Dependencies	Expansion
Restaurant Management	Business Module (`restaurant`)	Scaffolded	Digital menu, tables, orders, kitchen, loyalty	White-label host, Core entitlement, Payment (for paid orders), optional Accounting posting events	High after Wave 0–1
Cafe Management	Same module family as Restaurant	Scaffolded	Cafe operations subset of restaurant	Same as Restaurant	High
Digital Menu	Restaurant public surface	Scaffolded	Guest menu on tenant domain; optional local guest auth	White-label public site	High
CRM	Business Module (`crm`)	Scaffolded	Customers, leads, opportunities, pipelines, tasks	Core entitlement; Notification; optional AI/Messenger	High
Customer Club	Product capability on CRM/Restaurant (not Active registry module)	Not a dedicated Active module	Loyalty segments, points, tiers — design choice open	CRM and/or Restaurant + Notification + Wallet/Payment later	Medium until ownership decided
SMS Platform	Shared (`sms_panel`) + Core OTP path	Panel Scaffolded; OTP Active	Campaign SMS vs auth OTP separation	Providers (Payamak+); keep OTP separate	Medium
Wallet	Shared platform (future)	Not Active in registry	Stored value/credits	Payment + strong ledger discipline; possibly Accounting correlation	Later (P3)
Payment	Shared provider + adapters	Planned provider	Checkout, refunds, webhooks for subscriptions/commerce	PSP selection; Core subscriptions; Restaurant/Ecommerce	P1
Store Builder	Business (`ecommerce`)	Scaffolded	Catalog, cart, orders, shipments	File Storage, Payment, Core	After Wave 1
Website Builder	Business (`website_builder`)	Scaffolded	Sites, pages, blocks, forms, menus, media	File Storage/S3	After File Storage
Landing Builder	Capability of Website Builder	Scaffolded (via website_builder)	Marketing landers on tenant hosts	White-label + File Storage	With Website Builder
ERP	Program of modules led by Accounting	Accounting Active; broader ERP partial	Finance spine exists; supply chain/HRIS/manufacturing not claimed complete as ERP suite	Accounting + future inventory ops modules	Finance-ready; full ERP long-term
Gym	Future vertical (not registry Active)	UNKNOWN / Future	Memberships, classes, check-in — not specified in module registry	Prefer shared Appointment/Reservation kernel if multiple verticals	P3+
AI Assistant	Shared/Business (`ai_assistant`)	Scaffolded; provider Planned	Chat, KB, handoff; never money/compliance authority	AI provider Active; entitlement	After provider
Automation	Shared platform	Planned	Cross-module workflow triggers/actions	Real message bus	After bus
Workflow	Same family as Automation	Planned	Human+system workflow orchestration	Bus + governance/approvals patterns from Accounting 5.11	After bus
Chat	Business (`live_chat`)	Scaffolded	Embeddable widget, routing	Core; optional CRM/AI	Wave 4
Appointment	Future capability	Not Active registry module	Booking slots	Scheduling kernel decision pending	P3
Reservation	Restaurant-adjacent + generic booking	Not Active standalone	Tables/rooms/resources	Restaurant module and/or shared kernel	With Restaurant / later kernel
Marketplace	Business (`marketplace`)	Planned	Multi-vendor market	Ecommerce, Identity, Payment, Accounting settlement events	Wave 5

Appendix AI — Capability Narratives (planning depth)

AI-x — Restaurant Management

Placement: Business Module (restaurant)
Status: Scaffolded
Purpose: Digital menu, tables, orders, kitchen, loyalty
Dependencies: White-label host, Core entitlement, Payment (for paid orders), optional Accounting posting events
Expansion capability: High after Wave 0–1

Architectural guidance: Keep tenant isolation, entitlement gates, and API/event integration. If the capability touches money, route financial effects through Accounting Posting Engine contracts. If it sends messages, prefer Notification/SMS Panel rather than embedding providers in domain services. If it stores media, use File Storage.

AI-x — Cafe Management

Placement: Same module family as Restaurant
Status: Scaffolded
Purpose: Cafe operations subset of restaurant
Dependencies: Same as Restaurant
Expansion capability: High

Placement: Restaurant public surface
Status: Scaffolded
Purpose: Guest menu on tenant domain; optional local guest auth
Dependencies: White-label public site
Expansion capability: High

AI-x — CRM

Placement: Business Module (crm)
Status: Scaffolded
Purpose: Customers, leads, opportunities, pipelines, tasks
Dependencies: Core entitlement; Notification; optional AI/Messenger
Expansion capability: High

AI-x — Customer Club

Placement: Product capability on CRM/Restaurant (not Active registry module)
Status: Not a dedicated Active module
Purpose: Loyalty segments, points, tiers — design choice open
Dependencies: CRM and/or Restaurant + Notification + Wallet/Payment later
Expansion capability: Medium until ownership decided

AI-x — SMS Platform

Placement: Shared (sms_panel) + Core OTP path
Status: Panel Scaffolded; OTP Active
Purpose: Campaign SMS vs auth OTP separation
Dependencies: Providers (Payamak+); keep OTP separate
Expansion capability: Medium

AI-x — Wallet

Placement: Shared platform (future)
Status: Not Active in registry
Purpose: Stored value/credits
Dependencies: Payment + strong ledger discipline; possibly Accounting correlation
Expansion capability: Later (P3)

AI-x — Payment

Placement: Shared provider + adapters
Status: Planned provider
Purpose: Checkout, refunds, webhooks for subscriptions/commerce
Dependencies: PSP selection; Core subscriptions; Restaurant/Ecommerce
Expansion capability: P1

AI-x — Store Builder

Placement: Business (ecommerce)
Status: Scaffolded
Purpose: Catalog, cart, orders, shipments
Dependencies: File Storage, Payment, Core
Expansion capability: After Wave 1

AI-x — Website Builder

Placement: Business (website_builder)
Status: Scaffolded
Purpose: Sites, pages, blocks, forms, menus, media
Dependencies: File Storage/S3
Expansion capability: After File Storage

AI-x — Landing Builder

Placement: Capability of Website Builder
Status: Scaffolded (via website_builder)
Purpose: Marketing landers on tenant hosts
Dependencies: White-label + File Storage
Expansion capability: With Website Builder

AI-x — ERP

Placement: Program of modules led by Accounting
Status: Accounting Active; broader ERP partial
Purpose: Finance spine exists; supply chain/HRIS/manufacturing not claimed complete as ERP suite
Dependencies: Accounting + future inventory ops modules
Expansion capability: Finance-ready; full ERP long-term

AI-x — Gym

Placement: Future vertical (not registry Active)
Status: UNKNOWN / Future
Purpose: Memberships, classes, check-in — not specified in module registry
Dependencies: Prefer shared Appointment/Reservation kernel if multiple verticals
Expansion capability: P3+

AI-x — AI Assistant

Placement: Shared/Business (ai_assistant)
Status: Scaffolded; provider Planned
Purpose: Chat, KB, handoff; never money/compliance authority
Dependencies: AI provider Active; entitlement
Expansion capability: After provider

AI-x — Automation

Placement: Shared platform
Status: Planned
Purpose: Cross-module workflow triggers/actions
Dependencies: Real message bus
Expansion capability: After bus

AI-x — Workflow

Placement: Same family as Automation
Status: Planned
Purpose: Human+system workflow orchestration
Dependencies: Bus + governance/approvals patterns from Accounting 5.11
Expansion capability: After bus

AI-x — Chat

Placement: Business (live_chat)
Status: Scaffolded
Purpose: Embeddable widget, routing
Dependencies: Core; optional CRM/AI
Expansion capability: Wave 4

AI-x — Appointment

Placement: Future capability
Status: Not Active registry module
Purpose: Booking slots
Dependencies: Scheduling kernel decision pending
Expansion capability: P3

AI-x — Reservation

Placement: Restaurant-adjacent + generic booking
Status: Not Active standalone
Purpose: Tables/rooms/resources
Dependencies: Restaurant module and/or shared kernel
Expansion capability: With Restaurant / later kernel

AI-x — Marketplace

Placement: Business (marketplace)
Status: Planned
Purpose: Multi-vendor market
Dependencies: Ecommerce, Identity, Payment, Accounting settlement events
Expansion capability: Wave 5

Appendix AJ — Multi-Tenant Threat Model (documentation-derived)

Threat	Control in architecture
Cross-tenant data read	tenant_id filters; denial tests; no cross-tenant queries
Cross-tenant write	same + service authz
Host header tenant spoofing	resolution order + domain verification (custom domain verify still missing → residual risk)
Privilege escalation via Identity roles	Core memberships are SoT; Identity listing roles not operational
JWT theft	TLS; short-lived tokens (OTP expiry configured); HttpOnly cookie practices as implemented for subdomain auth (ops concern)
Service token leakage	hashed at rest; scoped
Journal tampering via UI	ADR-010; posting permissions; audit frameworks
AI data bleed	tenant-scoped KB only; no cross-tenant reads
Support break-glass	platform_admin logged

Appendix AK — Non-Functional Requirements Snapshot

NFR	Documented expectation	Current evidence
Multi-tenancy	Mandatory	Implemented in Core/Accounting paths
Auditability	Mandatory	Core audit + Accounting audit framework
API-first	Mandatory	Contracts + FE clients
Event-ready	Mandatory	Outbox pattern
Security secrets hygiene	Mandatory	env-based; backup notes
Observability	Suggested alerts	Minimal runbook
Performance SLOs	Not published	UNKNOWN
Availability SLO	Not published	UNKNOWN
DR	Runbooks exist	Execution cadence UNKNOWN

Appendix AL — Release & Branching Alignment

Development docs define branching and release strategies. Architecture implication:

Architecture changes require ADR/docs first when boundaries move.
Module registry/version fields should move with releases.
Production deploy steps must record Alembic procedure used.
Frontend and Accounting can release on different cadences if contracts remain compatible—API versioning discipline required.

Appendix AM — White-Label Readiness Rubric

Criterion	Status
Tenant brand fields	Present (architecture/progress)
Theme CSS variables	Partial runtime
Public tenant-site API	Present
Subdomain routing	Present
Subdomain SSL auto	Present
Custom domain storage	Present with pending verify
DNS/TXT verification	Missing
Guest vs member experiences	Partial / productized via tenant site
Ready for Restaurant guest menu	Not fully — polish + pay still needed

Appendix AN — Entitlement Key Taxonomy Guidance

Format: {service_key}.{resource}.{action}
Example: accounting.invoice.create

Rules for new modules:

Reserve prefix in module registry before coding.
Seed plan features for FREE/STARTER (or successor plans) intentionally.
Cache invalidation on feature_access.changed.
UI must hide and API must deny (never UI-only gates).

Appendix AO — Posting Integration Contract (for future modules)

When Restaurant/Ecommerce/CRM need financial effects:

Define posting profile / intent DTO with Accounting.
Prefer preview then post.
Emit domain event after operational success; Accounting posts and emits *.posted.
Never create JournalEntry rows locally.
Include tenant_id, idempotency key, source document ids.
Respect fiscal period open checks (failures are expected, not bugs).

Appendix AP — Celery / Async Job Catalog (known)

Job/area	Purpose
`process_outbox_events`	Publish pending outbox rows
SSL provision task	Expand tenant certs via SSH script
Future notification dispatch	Should live in Notification workers
Future report schedules	Accounting scheduled reports (phase 5.10 entities)

Appendix AQ — Frontend Module Onboarding Template

Create app/<module>/** routes
Add shell + nav entries entitlement-aware
Add typed API client (lib/<module>-api.ts)
Use DS components only
Wire AuthGuard + tenant header
Add scoreboard doc if enterprise completeness tracking needed
No mocks

Appendix AR — Backend Service Onboarding Template

backend/services/<name>/ structure per service architecture
Independent DB + Alembic
Shared-lib JWT validation
Tenant middleware/deps
Outbox for events
Register in Core + module-registry
Permissions + tests + docs

Appendix AS — Documentation Drift Prevention Checklist

Status only in progress/next-steps/roadmap (correct file)
Architecture docs avoid “done/not done” claims when possible
Registry Status fields updated same PR as code
Event catalog updated with producers
Conflicts table reviewed quarterly
Deprecated stubs for moved paths kept honest

Appendix AT — Financial Spine Diagram

flowchart LR
  OPS["Operational modules<br/>Restaurant · Ecommerce · CRM"] -->|posting intents / events| ACC["Accounting Service"]
  ACC --> PE["Posting Engine"]
  PE --> GL["General Ledger"]
  PE --> AUD["Audit / Compliance"]
  GL --> RPT["Reporting Engine"]
  OPS -->|payments| PAY["Payment Provider"]
  PAY -->|settlement events| ACC
  ACC -->|cash postings| TRY["Treasury"]

Appendix AU — Identity Spine Diagram

flowchart LR
  U["User"] --> FE["Frontend"]
  FE --> KC["Keycloak"]
  FE --> ID["Identity BFF"]
  ID --> KC
  ID --> COREOTP["Core OTP / Payamak"]
  FE --> CORE["Core users + memberships"]
  CORE --> ENT["Entitlement"]
  FE --> MOD["Business module APIs"]
  MOD --> ENT

Appendix AV — Edge Spine Diagram

flowchart TB
  DNS["DNS *.torbatyar.ir + custom"] --> NGX["Nginx 192.168.10.156"]
  NGX --> FE["Frontend :3000"]
  NGX --> API["Core :8000"]
  NGX --> ID["Identity :8001"]
  NGX --> AUTH["Keycloak :8080"]
  NGX --> ACC["Accounting :8002"]
  CEL["Celery on app host"] -->|SSH provision_ssl| NGX

Appendix AW — What “Done” Means for Platform Waves

Wave 0 Done

Accounting hostname smoke green
White-label product-accepted
Doc conflicts X1–X10 addressed or ticketed
AI provider decision recorded

Wave 1 Done

File Storage uploads work for at least one consumer
Notification delivers at least one channel for one event type
Payment webhook → subscription or order path proven
Bus publishes outbox events to a consumer service
Custom domain verify path proven
Membership sync proven with tests

Wave 2 Done

Restaurant can publish a digital menu on tenant host
CRM can manage a lead→opportunity path
Both gated by entitlement

Appendix AX — Stakeholder FAQ

Q: Is TorbatYar production-ready?
A: Foundation + Accounting are production-shaped; next-steps still require deploy verification and platform polish. Not full SuperApp-ready.

Q: Why did Accounting come before Restaurant?
A: Delivery history in progress shows Accounting 5.x completed; product decision preferring Restaurant remains Proposed and still valuable as next GTM vertical after white-label.

Q: Can we start Marketplace now?
A: No — depends on ecommerce, payment, identity maturity, accounting settlements.

Q: Can AI post vouchers?
A: Architecture forbids AI as sole authority for money; at most advisory with human/approval controls.

Q: Single database would be simpler—why not?
A: ADR-001 rejected shared DB to protect long-term modularity.

Appendix AY — Metrics to Start Measuring (recommended; not currently published as SLOs)

These are planning recommendations consistent with monitoring docs, not claimed existing dashboards:

Outbox pending/failed age
OTP send success rate
SSL provision success/latency
Entitlement cache hit ratio
Accounting post latency
5xx by service host
Cert days-to-expiry
Backup last success timestamp

Appendix AZ — Final Synthesis Paragraph

The platform’s architecture is coherent enough to support a long SuperApp journey. The limiting factor is no longer the absence of principles—it is the absence of shared horizontal services and scale machinery relative to the breadth of ambitions listed in the mission catalog. Execute Wave 0 and Wave 1 with discipline; then open verticals in dependency order. Protect tenant isolation and posting integrity above feature velocity. Keep documentation conflict debt near zero so the next master report is a delta, not a rewrite.

Document complete — Master Architecture Report v1.0 (2026-07-24) Path: docs/architecture-review/MASTER_ARCHITECTURE_REPORT.md

Appendix BA — Service Contracts Digest (from reference)

BA.1 Fundamental rules

No direct queries to another service database.
Database-per-service.
Inter-service channels only: REST, Webhook, Async Event, Outbox/Inbox.
Tenant-aware requests carry tenant_id (header X-Tenant-ID or token/event).

BA.2 Inter-service auth

Internal Service Tokens hashed in internal_service_tokens with scopes. End users authenticate with Keycloak JWT (and OTP JWT where applicable).

BA.3 Entitlement check contract

POST /api/v1/tenants/{tenant_id}/features/check
{ "feature_key": "accounting.invoice.create" }
→ { "tenant_id", "feature_key", "has_access", "reason" }

Naming: {service_key}.{resource}.{action} (examples include crm.lead.create, ecommerce.product.create).

BA.4 Core API groups (Phase 1 surface)

Health; Tenants (CRUD/suspend/activate); Domains (+ resolve); Plans & Features; Subscription + feature check; Service Registry.

BA.5 Standard responses

Errors via shared.responses.ErrorResponse (success=false, error.code/message/details). Lists via paginated Page (items + meta).

BA.6 Onboarding / tenant context

Contracts document Phase 4 onboarding APIs under /api/v1, requiring Bearer auth, with explicit note that external briefs call this Phase 3. Includes GET /api/v1/me for current user, memberships, and onboarding need.

BA.7 Implication for master plan

Contracts are the integration constitution. New modules must extend contracts/catalog/registry in the same change set as code—otherwise SuperApp integration decays into tribal knowledge.

Appendix BB — Disaster Recovery Targets

Metric	Initial target
RPO	≤ 24 hours (improve with more frequent backups)
RTO	≤ 8 hours for full stack restore

Scenario	Response summary
App host loss	New host, restore compose+env, restore DB dumps, repoint Nginx
Edge host loss	Rebuild Nginx from infra configs, restore certs/maps, re-provision
DB corruption	Restore last good dump; forward-fix if possible
Keycloak loss	Restore Keycloak DB + realm export; validate OIDC clients

Scale note: 24h RPO is acceptable for early SaaS; 1,000+ tenants with payment/marketplace will need tighter RPO and tested runbooks—treat as Wave 1/ops upgrade.

Appendix BC — Release Strategy Alignment

Semantic versioning: MAJOR breaking contracts/schema; MINOR compatible features/modules; PATCH fixes/docs/hardening.

Release notes must list features, fixes, migrations, env/config, provider changes, deprecations.

Migration order: Backup → per-service migrations (typically Core → Identity → business) → deploy compatible services → smoke auth/onboarding → then enable flags.

Rollback: prefer forward-fix; app rollback to previous image; DB downgrade only with tested path + restore point.

Hard rule: Do not ship half-enabled financial posting paths behind weak flags.

Appendix BD — Glossary Conflict & Updates Needed

docs/glossary.md still titles the Accounting section as "Accounting (future)" and describes Account as a planned 4-level structure even though Accounting 5.1–5.11 and FE scoreboard show Active delivery.

Preferred truth: Accounting terms are current platform vocabulary; glossary heading should drop "(future)" and note Phase 5.x delivered, with remaining future items (tax connectors, AI 5.12) called out separately.

This is documentation debt severity Medium—not a runtime defect, but it mis-trains new contributors.

Appendix BE — Program Roadmap Gantt (logical, not calendar dates)

gantt
    title TorbatYar Platform Sequencing (logical waves)
    dateFormat  X
    axisFormat %s
    section Wave0
    Accounting prod verify           :a1, 0, 1
    White-label polish               :a2, 0, 2
    Doc conflict cleanup             :a3, 0, 1
    AI provider decision             :a4, 1, 1
    section Wave1
    File Storage + S3                :b1, 2, 3
    Notification MVP                 :b2, 2, 3
    Payment provider                 :b3, 3, 3
    Message bus                      :b4, 4, 3
    Domain verify + RBAC invites     :b5, 3, 3
    Membership sync                  :b6, 3, 2
    section Wave2
    Restaurant digital menu          :c1, 6, 4
    CRM foundation                   :c2, 6, 4
    section Wave3
    Website/Landing builder          :d1, 10, 3
    Ecommerce store builder          :d2, 11, 4
    section Wave4
    Live Chat + AI assistant         :e1, 14, 4
    Smart Messenger / SMS panel      :e2, 15, 3
    section Wave5
    Automation/Workflow              :f1, 18, 4
    Marketplace                      :f2, 19, 5
    Wallet / Gym packs               :f3, 20, 4

Appendix BF — Decision Log Impact Matrix

Decision	Status	Impact if ignored
ADR-001 DB-per-service	Accepted	Accidental monolith DB
ADR-002 FE/BE split	Accepted	Entangled deploys
ADR-003 tenant_id	Accepted	Data leaks
ADR-004 Keycloak SSO	Accepted	Fragmented logins
ADR-005 Mobile OTP	Accepted	Weak IR market fit
ADR-006 Outbox	Accepted	Dual-write bugs
ADR-007 Dual memberships	Accepted	Must educate constantly
ADR-008 White-label config	Accepted	Hardcoded brands
ADR-009 Nginx SSL auto	Accepted	Manual cert ops pain
ADR-010 Posting engine	Accepted	Broken ledger integrity
Phase numbering	Accepted	Confused roadmaps
Restaurant first module	Proposed	Already superseded in practice by Accounting delivery—update decision
Documentation-as-software	Accepted	Drift returns

Appendix BG — Quality Gates Before Opening a PR for New Modules

Phase/module docs exist
Registry row Status accurate
Feature keys reserved
Tenant denial test included
No cross-DB import
Events catalogued if emitted
FE uses DS + real API
If money involved: posting contract reviewed
Progress/roadmap updated appropriately
No secrets committed

Appendix BH — Ops Runbook Index

Runbook	Path
Deployment overview	`docs/deployment/deployment.md`
Production hosts/env	`docs/deployment/production.md`
SSL/TLS	`docs/deployment/ssl.md`
Monitoring	`docs/deployment/monitoring.md`
Backup	`docs/deployment/backup.md`
Restore	`docs/deployment/restore.md`
Disaster recovery	`docs/deployment/disaster-recovery.md`

Architecture topology companion: docs/architecture/deployment-architecture.md.

Appendix BI — Scorecard Action Mapping

Low/mid score area	First action
Scalability 5	Message bus + DB capacity plan
Testing 6	Expand tenant isolation + contract suites; publish coverage expectations per service
Infrastructure 6	Implement suggested alerts; document CI
Enterprise SaaS 6	Complete Wave 1 shared services
Frontend 7	Finish white-label; module nav scalability
Security 7	Invites/RBAC + domain verify

Appendix BJ — Closing Cover Note for Reviewers

Reviewers should read sections 1, 12–18 first, then dive into appendices for evidence. Treat conflict tables as mandatory reading before changing roadmap. When disagreeing with a score, propose an evidence-backed adjustment tied to a doc or measurable gate—not intuition alone.

This file is the planning baseline as of 2026-07-24. Re-issue a delta master report when Wave 0 exits or when a new Active business module ships.

End of Master Architecture Report v1.0 — full synthesis

122 KiB Raw Blame History Unescape Escape