docs, obfuscation

2026-07-29 07:39:15 +03:00 · 2026-06-19 22:41:27 +02:00
parent 55cdcb49bf
commit b9f94fe005
57 changed files with 3229 additions and 105 deletions
--- a/docs/DRs/20100611_3_url_shortener.pdf
+++ b/docs/DRs/20100611_3_url_shortener.pdf
@@ -279,7 +279,7 @@ endobj
 endobj
 46 0 obj
 <<
-/Author (Android Cast project) /CreationDate (D:20260617220446+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260617220446+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+/Author (Android Cast project) /CreationDate (D:20260618174831+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260618174831+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
  /Subject (\(unspecified\)) /Title (URL shortener service \204 design review \(DR\)) /Trapped /False
 >>
 endobj
@@ -553,7 +553,7 @@ xref
 trailer
 <<
 /ID 
-[<3a7c0ee4bbf3482849eeadc12de9b9c8><3a7c0ee4bbf3482849eeadc12de9b9c8>]
+[<83c7ff4a46a2644aace09ed6f7e081cb><83c7ff4a46a2644aace09ed6f7e081cb>]
 % ReportLab generated PDF document -- digest (opensource)

 /Info 46 0 R
--- a/docs/DRs/20100612_1_scaling.pdf
+++ b/docs/DRs/20100612_1_scaling.pdf
@@ -498,7 +498,7 @@ endobj
 endobj
 79 0 obj
 <<
-/Author (Android Cast project) /CreationDate (D:20260617220446+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260617220446+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+/Author (Android Cast project) /CreationDate (D:20260618174831+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260618174831+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
  /Subject (\(unspecified\)) /Title (Platform scaling and multi-environment architecture \204 design review \(DR\)) /Trapped /False
 >>
 endobj
@@ -933,7 +933,7 @@ xref
 trailer
 <<
 /ID 
-[<cc552ef08a2fe35d84129cecaf25d843><cc552ef08a2fe35d84129cecaf25d843>]
+[<7d99cda1a76db27f24dc235d81baf7e5><7d99cda1a76db27f24dc235d81baf7e5>]
 % ReportLab generated PDF document -- digest (opensource)

 /Info 79 0 R
--- a/docs/DRs/20260616_rssh_routed_egress.pdf
+++ b/docs/DRs/20260616_rssh_routed_egress.pdf
@@ -324,7 +324,7 @@ endobj
 endobj
 51 0 obj
 <<
-/Author (Android Cast project) /CreationDate (D:20260617220453+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260617220453+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+/Author (Android Cast project) /CreationDate (D:20260618174832+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260618174832+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
  /Subject (\(unspecified\)) /Title (RSSH routed egress \(dev-only\) \204 design review \(DR\)) /Trapped /False
 >>
 endobj
@@ -663,7 +663,7 @@ xref
 trailer
 <<
 /ID 
-[<c1d94c835c02f8ed54a6427788bba047><c1d94c835c02f8ed54a6427788bba047>]
+[<ed6e2cbfecdbe9d49d63d210ed176bb8><ed6e2cbfecdbe9d49d63d210ed176bb8>]
 % ReportLab generated PDF document -- digest (opensource)

 /Info 51 0 R
--- a/docs/DRs/20260617_codec2_ulbw_voice.pdf
+++ b/docs/DRs/20260617_codec2_ulbw_voice.pdf
@@ -319,7 +319,7 @@ endobj
 endobj
 51 0 obj
 <<
-/Author (Android Cast project) /CreationDate (D:20260617220459+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260617220459+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
+/Author (Android Cast project) /CreationDate (D:20260618174832+02'00') /Creator (\(unspecified\)) /Keywords () /ModDate (D:20260618174832+02'00') /Producer (ReportLab PDF Library - \(opensource\)) 
  /Subject (\(unspecified\)) /Title (Codec2 / ultra-low-bandwidth voice \204 design review \(DR\)) /Trapped /False
 >>
 endobj
@@ -657,7 +657,7 @@ xref
 trailer
 <<
 /ID 
-[<cb8942224039a3f8bf18c924200f4ad4><cb8942224039a3f8bf18c924200f4ad4>]
+[<c52c2dec229f7f4121897008cb63143d><c52c2dec229f7f4121897008cb63143d>]
 % ReportLab generated PDF document -- digest (opensource)

 /Info 51 0 R
--- a/docs/DRs/20260618_repos_reorganizing.md
+++ b/docs/DRs/20260618_repos_reorganizing.md
@@ -0,0 +1,681 @@
+# Repository and microservice reorganization — design review (DR)
+
+<!-- doc-meta:start -->
+| Field | Value |
+|---|---|
+| Author | Anton Afanasyeu |
+| Revision | R0 |
+| Creation date | 2026-06-18 |
+| Last modification date | 2026-06-18 |
+| Co-authored | Cursor Agent (project assistant) |
+| Severity | high |
+| State | approved for planning |
+| Document type | DR |
+| Pre-requisite to | Gitea org `ac` repo creation; post-alpha full MS split (alpha may stay on monolith until Step 8+) |
+<!-- doc-meta:end -->
+
+\newpage
+\newpage
+
+---
+
+**Document type:** DR (Design Review)  
+**Source draft:** [docs/drafts/20260618_repos_reorganizing.txt](../drafts/20260618_repos_reorganizing.txt)  
+**PDF:** [20260618_repos_reorganizing.pdf](20260618_repos_reorganizing.pdf) · Regenerate: `bash scripts/build-all-docs-pdf.sh`  
+**Status:** PO-approved (2026-06-18) — **implementation phased**; monolith remains deployable until each step completes  
+**Scope:** Split `git://f0xx.org/android_cast` monolith into Gitea org **`ac`** — full microservice end-state, VM-first cloud path
+
+**Related:** [INFRA.md](../INFRA.md) · [BUILD_DEPLOY.md](../BUILD_DEPLOY.md) · [specs/20100612_1_scaling.md](../specs/20100612_1_scaling.md) · [orchestration/sim/cluster0/ARCHITECTURE.md](../../orchestration/sim/cluster0/ARCHITECTURE.md) · [examples/crash_reporter/backend/scripts/gitea/README.md](../../examples/crash_reporter/backend/scripts/gitea/README.md)
+
+**Documentation index:** [README.md](../README.md)
+
+---
+
+---
+
+---
+
+## Table of contents
+
+<!-- toc -->
+- [1. Executive summary](#1-executive-summary)
+- [2. Problem statement](#2-problem-statement)
+- [3. PO decisions (locked)](#3-po-decisions-locked)
+- [4. Current state](#4-current-state)
+- [5. Target architecture](#5-target-architecture)
+- [6. Gitea repo catalog](#6-gitea-repo-catalog)
+- [7. Public URL map](#7-public-url-map)
+- [8. Dependency graphs](#8-dependency-graphs)
+- [9. Monolith conversion steps](#9-monolith-conversion-steps)
+- [10. Microservice vs monolith comparison](#10-microservice-vs-monolith-comparison)
+- [11. Infrastructure and cloud](#11-infrastructure-and-cloud)
+- [12. ac-workspace and OTA versioning](#12-ac-workspace-and-ota-versioning)
+- [13. Risks and mitigations](#13-risks-and-mitigations)
+- [14. Changelog](#14-changelog)
+<!-- /toc -->
+
+---
+
+## 1. Executive summary
+
+**Question:** How should the androidcast monolith (`git://f0xx.org/android_cast`) be split into independent repos and deployable microservices?
+
+**Short answer:** Create Gitea org **`ac`** with **platform libraries**, **microservice APIs**, **thin backend UIs**, **client repos**, and **`ac-deploy`** (submodules **`ac-scripts`**). End-state is **full microservice** architecture. Delivery is **strictly ordered** — **[§9 Monolith conversion steps](#9-monolith-conversion-steps)** — with **`ac-ms-identity` as the gate** before any domain service split.
+
+**DR decision (R0):**
+
+| Item | Decision |
+|------|----------|
+| **Gitea org** | **`ac`** — `git://f0xx.org/ac/<repo>` |
+| **Architecture** | Full microservice end-state; phased migration from monolith |
+| **URL prefix** | **`/app/androidcast_project/`** (full path, locked) |
+| **Path-per-service** | `/issues/`, `/tickets/`, `/access/`, etc. — replace `/crashes/?view=` |
+| **Scripts** | **`ac-scripts`** separate; **`ac-deploy`** consumes it (submodule or PATH) |
+| **Workspace** | Optional **`ac-workspace`** — selective clone only; **not** build-all-in-one |
+| **Identity gate** | **Step 6** (`ac-ms-identity`) before domain MS extraction |
+| **Cloud** | VM lift-and-shift first; K8s optional later |
+| **Alpha** | Monolith may run in prod until Step 8+; no forced big-bang |
+
+---
+
+## 2. Problem statement
+
+The monolith bundles Android app, PHP backend (crashes, tickets, graphs, RBAC, remote access), builder, hub, orchestration, docs, and one submodule (url-shortener). This blocks:
+
+- Independent CI/CD and rollback per service
+- Clear ownership and OpenAPI contracts
+- Mapping repos to VM roles ([scaling SPEC §6.3](../specs/20100612_1_scaling.md))
+- Product URLs such as [issues](https://apps.f0xx.org/app/androidcast_project/crashes/?view=reports) vs [tickets](https://apps.f0xx.org/app/androidcast_project/crashes/?view=tickets) under distinct paths
+
+Today’s coupling: **one MariaDB**, **one session cookie** (`ac_crash_sess`, path `/app/androidcast_project`), **shared Auth.php** across consoles ([BUILD_DEPLOY.md](../BUILD_DEPLOY.md)).
+
+---
+
+## 3. PO decisions (locked)
+
+| # | Topic | Decision |
+|---|-------|----------|
+| 1 | Gitea org | **`ac`** |
+| 2 | Architecture | **Full microservice** (phased delivery) |
+| 3 | ac-scripts | Separate repo; **ac-deploy utilizes ac-scripts** |
+| 4 | Public URLs | Path-per-service under **`/app/androidcast_project/`** |
+| 5 | ac-workspace | Optional manifest; **not** unified build; supports multi-repo OTA |
+| 6 | Cloud | VM lift-and-shift; no K8s requirement at R0 |
+| 7 | Identity gate | **Approved** — identity MS before other MS splits |
+
+---
+
+## 4. Current state
+
+### 4.1 Monolith map
+
+| Monolith path | Future repo(s) | Notes |
+|---------------|----------------|-------|
+| `app/`, `ndk/`, `gradle/` | ac-mobile-android | third-party submodules |
+| `desktop/session-studio/` | ac-session-studio | Low coupling |
+| `docs/` | ac-docs | |
+| `scripts/` | ac-scripts | |
+| `orchestration/` | ac-deploy | cluster0, docker |
+| `examples/crash_reporter/backend/` | ac-ms-* + ac-be-* | **32 PHP classes**, 24 APIs |
+| `examples/build_console/` | ac-ms-build, ac-be-builder | Same DB `users` |
+| `examples/app_hub/` | ac-be-hub | Loads `/crashes/assets/` today |
+| `backend/url-shortener/` | ac-ms-url-shortener | Existing submodule |
+
+### 4.2 What is not a git repo
+
+- **Gitea** (infra on BE; scripts in ac-deploy)
+- **MariaDB**, **Janus** (:8089)
+- `examples/gentoo-portage-experimental/` (exclude or separate lab repo)
+
+---
+
+## 5. Target architecture
+
+```text
+Platform (Composer / static — not runtime MS)
+  ac-platform-php, ac-platform-db, ac-platform-web, ac-scripts, ac-docs
+
+Infrastructure
+  ac-deploy          submodules ac-scripts; docker, cluster0, nginx
+  ac-platform-edge   nginx BFF: routes + session cookie domain
+  ac-workspace       optional clone manifest (no unified build)
+
+Clients
+  ac-mobile-android, ac-mobile-ios (future), ac-session-studio
+
+Microservices (OpenAPI)
+  ac-ms-identity → ac-ms-rbac → ac-ms-devices
+  ac-ms-issues, ac-ms-tickets, ac-ms-graphs, ac-ms-remote-access
+  ac-ms-url-shortener, ac-ms-build, ac-ms-ota, ac-ms-notifications (later)
+
+Backend UI (thin → MS APIs)
+  ac-be-hub, ac-be-issues, ac-be-tickets, ac-be-graphs,
+  ac-be-remote-access, ac-be-access, ac-be-builder, ac-be-auth
+```
+
+**Consolidations vs initial PO sketch:**
+
+| Initial name | R0 decision |
+|--------------|-------------|
+| ac-be-console (monolith) | Dissolved into ac-be-issues … ac-be-access |
+| ac-ms-tracker | **ac-ms-issues** + **ac-ms-tickets** |
+| ac-ms-vpn-rssh + ac-ms-vpn-wireguard | **ac-ms-remote-access** (single control plane) |
+| ac-ms-analytics | **ac-ms-graphs** (+ BI later) |
+| ac-ms-orchestration | **ac-ms-build** + **ac-deploy** |
+| ac-ms-vcs | Not a repo — Gitea infra |
+
+---
+
+## 6. Gitea repo catalog
+
+Canonical: **`git://f0xx.org/ac/<repo>`**  
+HTTPS (Gitea UI): **`https://apps.f0xx.org/app/androidcast_project/git/ac/<repo>.git`**  
+Legacy: **`git://f0xx.org/android_cast`** → read-only mirror until retired.
+
+| ID | Repo | Git URL | Role |
+|----|------|---------|------|
+| W0 | ac-workspace | `git://f0xx.org/ac/ac-workspace` | Optional submodule manifest |
+| P0 | ac-platform-php | `git://f0xx.org/ac/ac-platform-php` | Composer: auth client, PDO, HTTP |
+| P1 | ac-platform-db | `git://f0xx.org/ac/ac-platform-db` | SQL migrations |
+| P2 | ac-platform-web | `git://f0xx.org/ac/ac-platform-web` | Shared CSS/JS/theme |
+| P3 | ac-platform-edge | `git://f0xx.org/ac/ac-platform-edge` | nginx routes + proxy |
+| P4 | ac-scripts | `git://f0xx.org/ac/ac-scripts` | CI, OTA, native codecs, PDF |
+| P5 | ac-docs | `git://f0xx.org/ac/ac-docs` | Documentation |
+| D0 | ac-deploy | `git://f0xx.org/ac/ac-deploy` | docker, cluster0; **uses P4** |
+| C0 | ac-mobile-android | `git://f0xx.org/ac/ac-mobile-android` | Android + ndk + third-party |
+| C1 | ac-mobile-ios | `git://f0xx.org/ac/ac-mobile-ios` | Future iOS |
+| C2 | ac-session-studio | `git://f0xx.org/ac/ac-session-studio` | Desktop analyzer |
+| S0 | ac-ms-template | `git://f0xx.org/ac/ac-ms-template` | New MS cookiecutter |
+| S1 | ac-ms-identity | `git://f0xx.org/ac/ac-ms-identity` | Users, login, 2FA, sessions |
+| S2 | ac-ms-rbac | `git://f0xx.org/ac/ac-ms-rbac` | Companies, privileges |
+| S3 | ac-ms-devices | `git://f0xx.org/ac/ac-ms-devices` | Device registry |
+| S4 | ac-ms-issues | `git://f0xx.org/ac/ac-ms-issues` | Crash/report ingest |
+| S5 | ac-ms-tickets | `git://f0xx.org/ac/ac-ms-tickets` | Ticket workflow |
+| S6 | ac-ms-graphs | `git://f0xx.org/ac/ac-ms-graphs` | Graph ingest/query |
+| S7 | ac-ms-remote-access | `git://f0xx.org/ac/ac-ms-remote-access` | WG + RSSH API |
+| S8 | ac-ms-url-shortener | `git://f0xx.org/ac/ac-ms-url-shortener` | Short links API |
+| S9 | ac-ms-build | `git://f0xx.org/ac/ac-ms-build` | Build worker API |
+| S10 | ac-ms-ota | `git://f0xx.org/ac/ac-ms-ota` | Channel manifests |
+| S11 | ac-ms-notifications | `git://f0xx.org/ac/ac-ms-notifications` | SMTP (post-alpha) |
+| B0 | ac-be-hub | `git://f0xx.org/ac/ac-be-hub` | Landing |
+| B1 | ac-be-issues | `git://f0xx.org/ac/ac-be-issues` | Issues UI |
+| B2 | ac-be-tickets | `git://f0xx.org/ac/ac-be-tickets` | Tickets UI |
+| B3 | ac-be-graphs | `git://f0xx.org/ac/ac-be-graphs` | Graphs UI |
+| B4 | ac-be-remote-access | `git://f0xx.org/ac/ac-be-remote-access` | RA admin UI |
+| B5 | ac-be-access | `git://f0xx.org/ac/ac-be-access` | RBAC admin UI |
+| B6 | ac-be-builder | `git://f0xx.org/ac/ac-be-builder` | Builder UI |
+| B7 | ac-be-auth | `git://f0xx.org/ac/ac-be-auth` | Login/register shell |
+| F1 | ac-ms-sfu-signaling | `git://f0xx.org/ac/ac-ms-sfu-signaling` | Future F1 |
+| F2 | ac-ms-media-transcode | `git://f0xx.org/ac/ac-ms-media-transcode` | Future VOD |
+
+Third-party codecs remain **submodules of C0** (upstream URLs); Gitea mirrors under `ac/`.
+
+---
+
+## 7. Public URL map
+
+**Base prefix (locked):** `https://apps.f0xx.org/app/androidcast_project`
+
+| Today | Target URL |
+|-------|------------|
+| `…/crashes/?view=reports` | `…/issues/` |
+| `…/crashes/?view=report&id=N` | `…/issues/N` |
+| `…/crashes/?view=tickets` | `…/tickets/` |
+| `…/crashes/?view=ticket&id=N` | `…/tickets/N` |
+| `…/crashes/?view=rbac` | `…/access/` |
+| `…/crashes/?view=remote_access` | `…/remote-access/` |
+| `…/crashes/?view=short_links` | `…/short-links/` |
+| `…/crashes/api/upload.php` | `…/issues/api/upload` |
+| `…/graphs/` | `…/graphs/` (unchanged) |
+| `…/build/` | `…/build/` (unchanged) |
+| `…/` (hub) | `…/` (unchanged) |
+| `…/git/` | `…/git/` (Gitea) |
+| `/v0/ota/` | `/v0/ota/` (unchanged) |
+
+**Cookie path:** remain `/app/androidcast_project` at **ac-platform-edge** until SSO tokens replace shared PHP session.
+
+**Migration:** 301 redirects from old `?view=` URLs for ≥ one release; update `BackendEndpoints.java`, `CrashSettings.java`.
+
+---
+
+## 8. Dependency graphs
+
+### 8.1 End-to-end — clients, edge, services
+
+```mermaid
+flowchart TB
+    subgraph clients [Clients]
+        AND[ac-mobile-android]
+        IOS[ac-mobile-ios]
+        HUB[ac-be-hub]
+        SS[ac-session-studio]
+    end
+
+    subgraph edge [Edge]
+        EDGE[ac-platform-edge]
+    end
+
+    subgraph core [Core MS — order matters]
+        ID[ac-ms-identity]
+        RB[ac-ms-rbac]
+        DV[ac-ms-devices]
+    end
+
+    subgraph domain [Domain MS]
+        IS[ac-ms-issues]
+        TK[ac-ms-tickets]
+        GR[ac-ms-graphs]
+        RA[ac-ms-remote-access]
+        UL[ac-ms-url-shortener]
+        BL[ac-ms-build]
+        OT[ac-ms-ota]
+    end
+
+    AND --> EDGE
+    IOS --> EDGE
+    HUB --> EDGE
+    SS -.->|offline files| AND
+    EDGE --> ID
+    EDGE --> IS & TK & GR & RA & UL & BL & OT & RB
+
+    ID --> RB
+    RB --> DV
+    IS --> DV & RB
+    TK --> RB
+    TK -.-> IS
+    GR --> ID
+    RA --> RB & DV
+    RA -.-> IS
+    UL --> RB
+    BL --> ID
+    OT --> BL
+    OT --> AND & IOS
+```
+
+### 8.2 Backend UI → microservice (requires)
+
+```mermaid
+flowchart LR
+    B7[ac-be-auth] --> S1[ac-ms-identity]
+    B5[ac-be-access] --> S2[ac-ms-rbac]
+    B1[ac-be-issues] --> S4[ac-ms-issues]
+    B2[ac-be-tickets] --> S5[ac-ms-tickets]
+    B3[ac-be-graphs] --> S6[ac-ms-graphs]
+    B4[ac-be-remote-access] --> S7[ac-ms-remote-access]
+    B6[ac-be-builder] --> S9[ac-ms-build]
+    B0[ac-be-hub] --> S1
+    B0 --> P2[ac-platform-web]
+
+    S4 --> S3[ac-ms-devices]
+    S4 --> S2
+    S5 --> S2
+    S7 --> S2 & S3
+```
+
+Every **B*** and **S*** also **requires** **P0** (ac-platform-php) and **P1** (ac-platform-db) via Composer — omitted from diagram for clarity.
+
+### 8.3 Platform and deploy layer
+
+```mermaid
+flowchart TB
+    D0[ac-deploy] --> P4[ac-scripts]
+    D0 --> P3[ac-platform-edge]
+    D0 --> P1[ac-platform-db]
+
+    P3 -->|routes| S1 & S4 & S5 & S6 & S7 & S8 & S9 & S10
+    P2[ac-platform-web] -->|static| B0 & B1 & B2
+
+    S1 & S2 & S3 & S4 & S5 --> P0[ac-platform-php]
+    S6 & S7 & S8 & S9 & S10 --> P0
+    B0 & B1 & B2 & B3 & B4 & B5 & B6 & B7 --> P0
+
+    P1 --> DB[(MariaDB / managed DB)]
+    S11[ac-ms-notifications] -.->|mail| S1
+```
+
+### 8.4 Service dependency matrix
+
+| Service | Requires (hard) | Requires (soft) | Required by |
+|---------|-----------------|-----------------|-------------|
+| ac-platform-db | — | — | All MS, migration jobs |
+| ac-platform-php | ac-platform-db | — | All MS, all BE UI |
+| ac-platform-web | — | — | ac-be-hub, all BE UI |
+| ac-platform-edge | ac-deploy nginx templates | all MS upstream addrs | All public HTTP |
+| ac-ms-identity | platform-db, platform-php | ac-ms-notifications | All MS, all BE UI, ac-ms-build |
+| ac-ms-rbac | ac-ms-identity | — | devices, issues, tickets, RA, url-shortener |
+| ac-ms-devices | ac-ms-rbac | ac-ms-identity | ac-ms-issues, ac-ms-remote-access |
+| ac-ms-issues | ac-ms-rbac, ac-ms-devices | — | ac-be-issues, mobile upload |
+| ac-ms-tickets | ac-ms-rbac | ac-ms-issues | ac-be-tickets |
+| ac-ms-graphs | ac-ms-identity | — | ac-be-graphs, mobile |
+| ac-ms-remote-access | ac-ms-rbac, ac-ms-devices | ac-ms-issues | ac-be-remote-access, mobile |
+| ac-ms-url-shortener | ac-ms-rbac | — | hub/admin UI |
+| ac-ms-build | ac-ms-identity | Gitea infra | ac-be-builder, ac-ms-ota |
+| ac-ms-ota | ac-ms-build | C0, C1 SHAs | mobile OTA clients |
+| ac-mobile-android | ac-ms-issues, ac-ms-graphs, ac-ms-remote-access APIs | ac-ms-ota | — |
+
+### 8.5 Repo creation waves (Gitea)
+
+```mermaid
+flowchart LR
+    W1[Wave 1: docs scripts deploy session-studio url-shortener] --> W2[Wave 2: platform-php platform-db platform-web]
+    W2 --> W3[Wave 3: ms-identity]
+    W3 --> W4[Wave 4: ms-rbac ms-devices]
+    W4 --> W5[Wave 5: ms-issues ms-tickets + be UI]
+    W5 --> W6[Wave 6: ms-graphs ms-remote-access ms-build + UI]
+    W6 --> W7[Wave 7: platform-edge mobile-android ms-ota]
+```
+
+---
+
+## 9. Monolith conversion steps
+
+Ordered steps for converting the monolith. **Do not skip gates.** Each step lists repos created/moved, monolith paths affected, and verification.
+
+### Step 1 — Gitea org and mirrors (no code move)
+
+**Goal:** Org **`ac`** exists; legacy mirror preserved.
+
+| Action | Detail |
+|--------|--------|
+| Create org | `ac` on f0xx.org Gitea |
+| Mirror | `android_cast` → read-only; plan `ac-workspace` or retire later |
+| Update docs | Pointer in INFRA.md, AGENTS.md |
+
+**Verify:** `git ls-remote git://f0xx.org/ac/ac-docs` (after Step 2) ; legacy push still works.
+
+**Requires:** nothing  
+**Enables:** all following steps
+
+---
+
+### Step 2 — Extract zero-coupling repos
+
+**Goal:** Repos with no runtime dependency on PHP monolith.
+
+| Repo | From monolith | CI |
+|------|---------------|-----|
+| ac-docs | `docs/` | PDF build |
+| ac-scripts | `scripts/` | lint/smoke |
+| ac-session-studio | `desktop/session-studio/` | unit tests |
+| ac-ms-url-shortener | `backend/url-shortener/` | PHPUnit (change remote URL only if already split) |
+| ac-deploy | `orchestration/` + nginx seeds | docker compose smoke |
+
+**ac-deploy** submodules **ac-scripts** at pinned SHA.
+
+**Verify:** Each repo builds independently; monolith submodule paths updated OR mirror dual-push during transition.
+
+**Requires:** Step 1  
+**Enables:** Steps 3–4
+
+---
+
+### Step 3 — Platform libraries (foundation)
+
+**Goal:** Shared code leaves monolith as Composer packages — **no MS split yet**.
+
+| Repo | Extract from |
+|------|--------------|
+| ac-platform-db | `sql/`, migrations from crash_reporter + url-shortener |
+| ac-platform-php | Auth*, Database, Rbac helpers, bootstrap patterns, `shared_session.php` |
+| ac-platform-web | `crashes/assets/`, shared theme referenced by hub |
+
+Monolith **requires** packages via Composer; behavior unchanged.
+
+**Verify:** Monolith tests green; single login still works across hub/crashes/build.
+
+**Requires:** Step 2  
+**Enables:** Step 4 (identity)
+
+---
+
+### Step 4 — Microservice template and OpenAPI baseline
+
+**Goal:** Cookiecutter + contract layout for all MS.
+
+| Repo | Action |
+|------|--------|
+| ac-ms-template | Copy url-shortener + platform-php wiring |
+| ac-docs | Add `openapi/` stubs per service |
+
+**Verify:** Scaffold new empty MS from template; deploy locally via ac-deploy.
+
+**Requires:** Step 3  
+**Enables:** Step 5
+
+---
+
+### Step 5 — Edge proxy (routing shell)
+
+**Goal:** **ac-platform-edge** nginx config routes paths; still proxies to **monolith** PHP until MS exist.
+
+| Action | Detail |
+|--------|--------|
+| Deploy edge config | Map `/issues/` → monolith `?view=reports` internally (temporary) |
+| Cookie | Single path `/app/androidcast_project` |
+
+**Verify:** `curl -I` new paths return 200 via rewrite; old URLs still work.
+
+**Requires:** Step 2 (ac-deploy)  
+**Enables:** Step 10 URL cutover
+
+---
+
+### Step 6 — Identity microservice (GATE)
+
+**Goal:** **ac-ms-identity** owns users, login, register, 2FA, session issuance.
+
+| Repo | From monolith |
+|------|---------------|
+| ac-ms-identity | Auth*, UserRepository, AuthTotp*, AuthRegistration*, … |
+| ac-be-auth | login/register views (thin) |
+
+Monolith/builder **call identity** for auth (HTTP or shared session bridge during transition).
+
+**Verify:** Login at `/app/androidcast_project/` + builder; sessions valid; `./scripts/test_rbac_api.sh` still passes against bridged auth.
+
+**Requires:** Steps 3, 4  
+**Enables:** Steps 7, 9, 11 — **nothing else splits before this**
+
+---
+
+### Step 7 — RBAC and devices microservices
+
+**Goal:** Company scope and device registry are independent APIs.
+
+| Repo | From monolith |
+|------|---------------|
+| ac-ms-rbac | Rbac*, RbacAdmin*, companies API |
+| ac-ms-devices | DeviceRepository |
+
+**Verify:** Upload still registers device; RBAC panel works via APIs.
+
+**Requires:** Step 6  
+**Enables:** Steps 8, 9
+
+---
+
+### Step 8 — Issues and tickets (domain core)
+
+**Goal:** Split PO’s primary URL surfaces.
+
+| Repo | From monolith |
+|------|---------------|
+| ac-ms-issues | upload, Report*, Tag*, reports API |
+| ac-ms-tickets | Ticket*, attachments |
+| ac-be-issues | reports views + JS |
+| ac-be-tickets | tickets views + JS |
+
+**Edge** routes `/issues/` → S4/B1, `/tickets/` → S5/B2.
+
+**Verify:** Mobile upload to new URL; web issue/ticket lists; E2E ticket workflow.
+
+**Requires:** Step 7  
+**Enables:** Step 9 (RA links to issues)
+
+---
+
+### Step 9 — Graphs and remote access
+
+| Repo | From monolith |
+|------|---------------|
+| ac-ms-graphs | GraphRepository, graph_* API |
+| ac-ms-remote-access | RemoteAccess*, WireGuard*, Rssh* |
+| ac-be-graphs | graphs UI |
+| ac-be-remote-access | remote_access view |
+
+**Verify:** `BackendEndpoints` graph URL; RA E2E (`ra_e2e_cli.sh`); mobile RA API.
+
+**Requires:** Steps 7, 8 (RA → devices, issue links)  
+**Enables:** Step 11
+
+---
+
+### Step 10 — Hub, access UI, URL migration
+
+| Repo | Action |
+|------|--------|
+| ac-be-hub | Extract app_hub; use **ac-platform-web** assets |
+| ac-be-access | RBAC UI → calls ac-ms-rbac |
+| ac-platform-edge | Enable **301** from `/crashes/?view=*` to new paths |
+
+**Verify:** Hub cards link to `/issues/`, `/tickets/`; no broken CSS.
+
+**Requires:** Steps 5, 8, 9  
+**Enables:** Step 11
+
+---
+
+### Step 11 — Build and OTA pipeline
+
+| Repo | From monolith |
+|------|---------------|
+| ac-ms-build | BuildRunner, build APIs |
+| ac-be-builder | build_console UI |
+| ac-ms-ota | OTA manifest assembly |
+| ac-mobile-android | `app/`, `ndk/`, gradle (extract from monolith) |
+
+**Verify:** Builder triggers APK; OTA channel publishes; manifest lists android (+ ios when C1 exists).
+
+**Requires:** Step 6 (identity for builder users)  
+**Enables:** Step 12
+
+---
+
+### Step 12 — Optional workspace and monolith retirement
+
+| Action | Detail |
+|--------|--------|
+| ac-workspace | Publish optional `.gitmodules` manifest |
+| Retire | Stop commits to `android_cast` monolith; archive mirror |
+| Gitea migrate | Update scripts for org `ac` ([gitea README](../../examples/crash_reporter/backend/scripts/gitea/README.md)) |
+
+**Verify:** Fresh clone via ac-workspace or individual repos; prod deploy from ac-deploy only.
+
+**Requires:** Steps 1–11 complete for services in scope  
+**Enables:** cloud VM scaling, future F1/F2 MS
+
+---
+
+### Step 13 — Notifications and cloud hardening (post-alpha)
+
+| Repo | Action |
+|------|--------|
+| ac-ms-notifications | Extract AuthMailer; wire 2.x mail when unblocked |
+| ac-deploy | Managed DB DSN templates; cluster0 → cloud VM roles |
+
+**Requires:** Step 6; mail infra (developer)  
+**Enables:** full 2FA mail E2E
+
+---
+
+### Conversion step summary (quick reference)
+
+| Step | Name | Gate |
+|------|------|------|
+| 1 | Gitea org `ac` | — |
+| 2 | docs, scripts, deploy, session-studio, url-shortener | — |
+| 3 | platform-php, platform-db, platform-web | — |
+| 4 | ms-template, OpenAPI | — |
+| 5 | platform-edge (shell) | — |
+| 6 | **ms-identity**, be-auth | **GATE** |
+| 7 | ms-rbac, ms-devices | after 6 |
+| 8 | ms-issues, ms-tickets, be-issues, be-tickets | after 7 |
+| 9 | ms-graphs, ms-remote-access, be UI | after 7–8 |
+| 10 | be-hub, be-access, URL 301 | after 8–9 |
+| 11 | ms-build, ms-ota, mobile-android | after 6 |
+| 12 | ac-workspace, retire monolith | after 1–11 |
+| 13 | notifications, cloud | post-alpha |
+
+---
+
+## 10. Microservice vs monolith comparison
+
+| Criterion | Full microservice (PO choice) | Modular monolith |
+|-----------|------------------------------|------------------|
+| Independent deploy | Yes — per MS/UI repo | Single PHP deploy |
+| Failure isolation | Stronger | Shared FPM pool |
+| Auth complexity | Needs identity MS + edge early | Works today |
+| URL clarity | `/issues/`, `/tickets/` | `?view=` parameters |
+| Ops load | More nginx, repos, logs | One sync path ([INFRA.md](../INFRA.md)) |
+| Alpha risk | High if before Step 6 | Lower |
+| Cloud mapping | 1:1 to VM roles | Lift entire tree |
+| Rollback | Revert one repo SHA | Revert one commit |
+
+PO choice is approved with **Step 6 gate** enforced in [§9](#9-monolith-conversion-steps).
+
+---
+
+## 11. Infrastructure and cloud
+
+| Stage | Pattern |
+|-------|---------|
+| **Prod today** | FE TLS → BE :80 nginx + PHP-FPM + MariaDB |
+| **cluster0 lab** | cast01–03; NFS config only; GTID DB ([ARCHITECTURE.md](../../orchestration/sim/cluster0/ARCHITECTURE.md)) |
+| **Cloud phase A** | 4–6 VMs: be-web, be-data, be-ops, be-build ([scaling §6.3](../specs/20100612_1_scaling.md)) |
+| **Cloud phase B** | Managed DB; DSN in secrets (not in git) |
+| **Cloud phase C** | K8s optional — not required at R0 |
+
+**Inter-service calls:** HTTP on private VLAN / localhost initially; OpenAPI in ac-docs. No service mesh at R0.
+
+**ac-deploy** ships Ansible/docker-compose per VM role; submodules **ac-scripts**.
+
+---
+
+## 12. ac-workspace and OTA versioning
+
+**ac-workspace** — optional; lists repo SHAs for a release train. **Not** a unified Gradle/PHP build.
+
+**ac-ms-ota** manifest (same product version, per-platform SHAs):
+
+```json
+{
+  "channel": "staging",
+  "version": "00.02.00.00",
+  "artifacts": {
+    "android": { "repo": "ac-mobile-android", "git_sha": "abc123" },
+    "ios": { "repo": "ac-mobile-ios", "git_sha": "def456" }
+  }
+}
+```
+
+---
+
+## 13. Risks and mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Auth split breaks all consoles | Step 6 gate; session bridge during transition |
+| Hub broken CSS | ac-platform-web before ac-be-hub (Step 3 before 10) |
+| Mobile upload URL change | Parallel endpoints + `BackendEndpoints` normalization |
+| DB schema drift | ac-platform-db single migration stream |
+| Too many repos to bump | Composer semver for P0; not @common submodule diamond |
+| Alpha blocked | Monolith stays prod until Step 8+ complete per service |
+| PO BE learning curve | ac-ms-template, ac-deploy, OpenAPI, localhost HTTP |
+
+---
+
+## 14. Changelog
+
+| Rev | Date | Change |
+|-----|------|--------|
+| R0 | 2026-06-18 | Initial DR from draft; PO locked org `ac`, full MS, URL prefix, identity gate; §9 conversion steps; dependency graphs |
--- a/docs/DRs/20260618_repos_reorganizing.pdf
+++ b/docs/DRs/20260618_repos_reorganizing.pdf