TorbatYar/docs/current-architecture-review.md

# DEPRECATED — Current Architecture Documentation Review

> **Status:** Deprecated historical inventory (2026-07-22).  
> **Superseded by:** [docs/README.md](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.