# 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 |
