12c8615615
Adds accounting-service PATCH/archive, fiscal helpers, COA templates and setup status, plus SuperApp Accounting UI (DS, scoreboard, masters, vouchers, ledger, ops modules) with session refresh and HTTPS public API URLs. Co-authored-by: Cursor <cursoragent@cursor.com>
297 lines
18 KiB
Markdown
297 lines
18 KiB
Markdown
# 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.
|