TorbatYar/docs/current-architecture-review.md

DEPRECATED — Current Architecture Documentation Review

Status: Deprecated historical inventory (2026-07-22).
Superseded by: docs/README.md and the consolidated documentation tree.
Kept for audit trail only — do not update.

Date: 2026-07-22
Scope: Read-only inventory of architecture / structure / progress documentation in the TorbatYar (SuperApp) repository.
Action taken: No existing documentation was modified at review time. This review file is retained as history.

---

1. Discovered documents

Search covered the whole repo for architecture-related markdown and naming patterns (architecture*, design*, database*, progress*, roadmap*, ADR*, deployment*, services*, etc.).

1.1 Core docs (docs/)

#	Path
1	docs/architecture.md
2	docs/database_schema.md
3	docs/services_contracts.md
4	docs/developer_guide.md
5	docs/progress.md
6	docs/last_step.md

1.2 Root & package READMEs

#	Path
7	README.md
8	backend/README.md
9	frontend/README.md
10	backend/services/README.md
11	backend/core-service/alembic/README.md

1.3 Service READMEs (backend/services/*/README.md)

#	Path
12	backend/services/identity-access/README.md
13	backend/services/accounting/README.md
14	backend/services/crm/README.md
15	backend/services/ecommerce/README.md
16	backend/services/restaurant/README.md
17	backend/services/website_builder/README.md
18	backend/services/live_chat/README.md
19	backend/services/ai_assistant/README.md
20	backend/services/smart_messenger/README.md
21	backend/services/sms_panel/README.md
22	backend/services/link_shortener/README.md
23	backend/services/file_storage/README.md
24	backend/services/notification/README.md

1.4 Related non-markdown / ops material (not architecture docs, but architecture-relevant)

These are not architecture documents, but they encode production architecture decisions and are currently undocumented (or only partially documented) in docs/:

Path / area	Why it matters
infrastructure/nginx/torbatyar.ir.conf	Live reverse-proxy / TLS / tenant host routing
infrastructure/nginx/provision_ssl.py	Auto SSL expand for tenant domains
infrastructure/nginx/torbatyar-tenant-ssl.map	Per-tenant HTTPS redirect readiness
infrastructure/deploy/.env.production.example	Production env contract (incl. SSL_PROVISION_*)
infrastructure/keycloak/realm/superapp-realm.json	SSO realm / clients / redirect URIs
docker-compose.yml	Runtime topology (Core, Identity, Keycloak, FE, Celery, Postgres, Redis)
.env.example	Config surface area
scripts/deploy_*.py	Operational deploy procedures (not product docs)

1.5 Patterns searched but not found

No dedicated files matching:

• ADR* / architecture decision records
• roadmap* / next-step* (except docs/last_step.md)
• design* / system* / engineering* / conventions* / principles* as standalone docs
• docs/ deployment guide
• AGENTS.md / CONTRIBUTING.md / CHANGELOG.md at repo root

Total architecture-related markdown documents reviewed: 24

---

2. Purpose of each document

Core docs

Document	Purpose
docs/architecture.md	Canonical high-level architecture: FE/BE split, multi-tenancy, Core responsibilities, tenant resolution, entitlement, outbox, identity layers (SSO + OTP), white-label intent, Phase 4 onboarding model.
docs/database_schema.md	Schema reference for core_platform_db and identity_access_db, plus conceptual schemas for future business-service databases.
docs/services_contracts.md	Inter-service communication rules, event envelope, entitlement check API, Core APIs, onboarding/tenant-context contracts, Identity auth APIs.
docs/developer_guide.md	Developer onboarding: prerequisites, Docker/local setup, env vars, folder layout, Alembic/pytest/Celery, how to add a new service.
docs/progress.md	Phase-by-phase checklist of what was delivered; backlog of remaining work. Primary status source of truth.
docs/last_step.md	Narrative of the latest completed delivery (Phase 4 / brief Phase 3) and proposed next phase (white-label runtime).

Package READMEs

Document	Purpose
README.md	Project entrypoint: overview, quick start, links to docs/, high-level tree.
backend/README.md	Backend boundary, tree, Core run/test commands, no-UI rule.
frontend/README.md	Frontend boundary, stack versions, run commands, white-label note.
backend/services/README.md	States that services/ holds future service placeholders and architecture rules.
backend/core-service/alembic/README.md	How to create/apply/downgrade Core Alembic migrations.

Service READMEs

Document	Purpose
identity-access/README.md	Real Identity & Access service: Keycloak BFF, DB, run/test, basic OIDC flow.
accounting … notification READMEs (12 files)	Placeholder scope statements: intended responsibilities, independent DB name, entitlement prefix, API/event-only rule.

---

3. Validity assessment

Legend:

• Valid — accurate enough to trust as current guidance
• Partially valid — still useful but contains stale or incomplete claims
• Placeholder-valid — intentionally aspirational / not yet implemented (OK if labeled clearly)
• Stale — claims that contradict current code / fresher docs

Document	Validity	Notes
docs/progress.md	Valid (best status doc)	Reflects phases 1–4 done, JIT done, nginx+SSL done, white-label partial.
docs/last_step.md	Mostly valid	Best narrative of “what just shipped” and next phase; white-label wording is transitional.
docs/architecture.md	Partially valid	Core principles still correct; several operational claims stale (JIT deferred, nginx later, “only Core implemented”).
docs/database_schema.md	Mostly valid	Core/Identity schema docs remain useful; future service DBs correctly marked conceptual.
docs/services_contracts.md	Partially valid	Onboarding/Identity contracts largely correct; missing newer public tenant-site + SSL; JIT 403 note may be outdated.
docs/developer_guide.md	Partially valid	Setup still useful; services/ “all placeholder”, missing Identity/env/SSL/production ops, possible API client naming confusion.
README.md	Partially valid	Quick start OK; claims only phases 1–2; tree omits infrastructure/, scripts/.
backend/README.md	Partially valid	Boundary rules OK; services/ still called placeholder-only.
frontend/README.md	Partially valid	Separation OK; does not describe onboarding/tenant host/SSO pages; cites api-client.ts while primary client is api.ts (both files exist).
backend/services/README.md	Stale	Says no services implemented in Phase 1 / only READMEs — Identity is implemented.
alembic/README.md	Valid	Narrow and accurate for Core migrations.
identity-access/README.md	Partially valid	Correct as a real service, but API list incomplete vs contracts (mobile/session APIs).
Business service READMEs (12)	Placeholder-valid	Correctly labeled unimplemented; still useful as future module map.

---

4. Overlaps

Topic	Documents that cover it	Overlap assessment
FE/BE separation rules	architecture.md §2.1, developer_guide.md, README.md, backend/README.md, frontend/README.md	Heavy overlap — same rule repeated 5 times. Keep once in architecture; short pointer elsewhere.
Database-per-service / no cross-DB	architecture.md, services_contracts.md, services/README.md, most service READMEs	Intentional repetition; OK if architecture is canonical and others link to it.
Phase status / what is done	progress.md, last_step.md, README.md, architecture.md intro	Conflict risk — status should live only in progress.md (+ short pointer in last_step.md).
Onboarding / Phase 4	architecture.md §11, services_contracts.md §7, progress.md, last_step.md, database_schema.md	Complementary if roles are clear: architecture=model, contracts=API, progress=checklist, last_step=narrative.
Identity / SSO / OTP	architecture.md, services_contracts.md, progress.md, identity-access/README.md	Overlap acceptable; Identity README should not duplicate full contracts.
White-label	architecture.md §10, frontend/README.md, progress.md, last_step.md	Overlap + inconsistency on “done vs partial”.
Future service list	architecture.md, database_schema.md conceptual DBs, 12 service READMEs	Triple map of the same modules — consolidate later.
How to run the stack	README.md, developer_guide.md, backend/README.md, frontend/README.md	Moderate overlap; root README should stay the short path.

---

5. Obsolete or stale claims

Claim	Where	Why obsolete / stale
Repo includes only Phase 1 + Phase 2	README.md	Phases 3–4 are delivered per progress.md.
In Phase 1 only Core is implemented; everything under services/ is placeholder	architecture.md, backend/README.md, developer_guide.md, backend/services/README.md	Identity & Access is a real implemented service.
JIT Core user from Keycloak JWT is deferred / yields 403	architecture.md §11, services_contracts.md §7	JIT implemented in UserService.resolve_current; marked done in progress.md / last_step.md.
Nginx/Traefik added in later phases	architecture.md §9	Production nginx + TLS + tenant auto-SSL are in place.
White-label is only static theme.config.json	older framing in architecture / last_step residual wording	Partial runtime exists: GET /public/tenant-site, TenantSitePage, subdomain-aware useTheme.
Outbox “real publish later”	architecture.md / workers commentary	Still largely true for message bus, but progress backlog already tracks it — keep, but don’t imply whole infra is unimplemented.
Admin login is a dedicated OTP UI	older progress wording (partially corrected)	Admin login now routes through central SSO; OTP still exists via Identity/Keycloak + Core APIs.

Not obsolete (still intentionally open):

• Real payment gateway
• Real DNS/TXT custom-domain verification
• Membership/plan auto-provision on legacy POST /admin/tenants
• First real business module (Restaurant etc.)
• Advanced permissions / invites
• Independent Subscription service
• Real message bus

---

6. Missing topics

Topics that are implemented or operationally real but poorly / not documented in architecture docs:

1. Production deployment topology — hosts (192.168.10.162 app, 192.168.10.156 nginx), domains (torbatyar.ir, api., identity., auth., *.torbatyar.ir).
2. Nginx routing & TLS model — apex vs service hosts vs tenant subdomains; HTTP→HTTPS rules; LE cert expand.
3. Automatic tenant SSL provisioning — SSL_PROVISION_*, Celery task provision_domain_ssl, provision_ssl.py.
4. Public tenant site API & UX — GET /api/v1/public/tenant-site, guest landing vs member services on subdomain.
5. Cross-subdomain auth cookies — cookie Domain=.torbatyar.ir, login redirect via apex.
6. Alembic production practice — upgrade 0001_initial && stamp head used in compose (important operational caveat vs “upgrade head”).
7. Phase numbering glossary — brief “Phase 3” vs docs “فاز ۳ OTP” vs docs “فاز ۴ onboarding”.
8. ADRs / decision log — no Architecture Decision Records.
9. Security model summary — platform_admin vs tenant roles vs Identity memberships (two membership tables).
10. Observability / logging / backup / disaster recovery — absent.
11. CI/CD & git workflow — Gitea remote exists; no architecture doc.
12. Frontend API client map — lib/api.ts vs lib/api-client.ts roles.
13. Celery queues & SSL worker networking — worker must reach nginx host over SSH.
14. Keycloak theme / mobile OTP unified login UX — implemented; scattered across docs.
15. Roadmap document — only last_step.md + backlog bullets; no dedicated roadmap.

---

7. Conflicting information

Conflict	Doc A	Doc B / Reality	Preferred truth
Current phase coverage	README: phases 1–2	progress: phases 1–4 done	progress.md
Are services implemented?	services/README.md: none	Identity service exists	Identity is real; others placeholder
JIT provisioning	architecture/contracts: not done / 403	progress/last_step + user_service.py: done	JIT done (edge cases remain)
Reverse proxy / TLS	architecture: later	progress + nginx configs: done	Nginx/TLS done
White-label runtime	architecture: config/theme file framing; last_step: next phase	progress: partial (tenant-site, TenantSitePage, useTheme)	Partial — next phase to finish
Phase “3” meaning	progress: OTP = فاز ۳	brief/architecture/last_step: onboarding = Phase 3 / docs فاز ۴	Needs explicit glossary
Frontend API entry	developer_guide / frontend README: api-client.ts	Main typed client used by app is largely api.ts	Document both or consolidate
Dual tenant_memberships	database_schema explains Core vs Identity	Easy to miss; contracts/architecture mention lightly	Must stay explicit everywhere memberships are discussed

---

8. Recommendations

8.1 Do not rewrite everything yet

Wait for approval (per request). When approved, prefer reconcile + slim, not a brand-new parallel doc set that duplicates again.

8.2 Proposed documentation roles (target model)

Document	Should become
docs/architecture.md	Canonical architecture (principles, components, tenancy, identity, entitlement, events). Status claims removed or linked to progress.
docs/database_schema.md	Canonical data model only.
docs/services_contracts.md	Canonical API/event contracts only (include public tenant-site).
docs/progress.md	Only status checklist (what is done / open).
docs/last_step.md	Latest delivery narrative + next-step proposal (or rename to next-steps.md).
docs/developer_guide.md	How to run/develop locally.
README.md	Short intro + links; no stale phase claims.
New (recommended): docs/deployment.md	Production topology, nginx, TLS, SSL auto-provision, env vars.
New (recommended): docs/adr/	Short decision records for major choices.
Service READMEs	Identity: keep real; business modules: keep placeholders but link to architecture module map.

8.3 Immediate reconciliation items (when editing is approved)

1. Fix stale JIT / nginx / “phases 1–2 only” / “all services placeholder” statements.
2. Add a phase numbering glossary (brief vs internal).
3. Document tenant subdomain runtime (public site, theme, cookies, SSL).
4. Update Identity README API table to match contracts.
5. Clarify api.ts vs api-client.ts.
6. Update root tree to include infrastructure/ and scripts/.

8.4 What not to do

• Do not create a second “full architecture” that competes with architecture.md without retiring overlaps.
• Do not treat placeholder service READMEs as implementation status.
• Do not mix roadmap, status, and architecture in one file.

8.5 Suggested reading order (today)

1. docs/progress.md + docs/last_step.md — current truth
2. docs/architecture.md — design intent (discount stale ops claims)
3. docs/database_schema.md + docs/services_contracts.md
4. README.md + developer/frontend/backend READMEs
5. identity-access/README.md + other service placeholders

---

Appendix A — Inventory matrix (compact)

#	Document	Purpose class	Valid?	Obsolete bits?	Overlaps
1	docs/architecture.md	Architecture	Partial	JIT, nginx, Core-only	High
2	docs/database_schema.md	Data model	Mostly	Minor	Medium
3	docs/services_contracts.md	Contracts	Partial	JIT 403; missing public site	Medium
4	docs/developer_guide.md	Dev ops	Partial	placeholders; env gaps	Medium
5	docs/progress.md	Status	Yes	—	With last_step
6	docs/last_step.md	Status/narrative	Mostly	White-label nuance	With progress
7	README.md	Entry	Partial	Phase 1–2 only	High
8	backend/README.md	Package	Partial	placeholders	Medium
9	frontend/README.md	Package	Partial	incomplete FE map	Medium
10	backend/services/README.md	Package	Stale	“none implemented”	High
11	alembic/README.md	Tooling	Yes	—	Low
12	identity-access/README.md	Service	Partial	incomplete APIs	Medium
13–24	Business service READMEs	Placeholders	Placeholder-valid	N/A if labeled	With architecture module list

---

Appendix B — Approval gate

No further architecture documentation changes will be made until approval.

When approved, recommended first deliverables:

1. Reconcile stale claims in existing docs (minimal edits).
2. Add docs/deployment.md.
3. Optionally introduce docs/adr/ and a slim docs/roadmap.md (or rename last_step.md).

Awaiting decision before creating the final architecture documentation set.