# Architecture Overview — trust.cogsaustralia.org

The operator subdomain. **Important: the local repo for this subdomain is intentionally near-empty.** The site's behaviour comes from server-side symlinks, not local code. Documented below.

Living doc — see root [ARCHITECTURE.md](../ARCHITECTURE.md) for the operating-layer conventions including the strong-rule that this file must be updated whenever a structural change lands.

## 1. Project Structure

### Local repo (this folder)

```text
trust.cogsaustralia.org/
├── ARCHITECTURE.md       # this file
└── README.md             # one-line: "# trust-admin / trust.cogsaustralia.org/admin"
```

### Server docroot (what actually serves users)

```text
/home4/cogsaust/trust.cogsaustralia.org/
├── admin → /home4/cogsaust/public_html/admin     # symlink to apex admin/
├── _app  → /home4/cogsaust/public_html/_app      # symlink to apex _app/
└── (any other content placed here directly)
```

The two server-side symlinks are the active mechanism — created during the `trust-subdomain-migration` Blueprint (closed 2026-05-27). They are NOT represented in the local repo (deliberate trade-off — recording them in the repo would require either real folders or a deploy.sh post-step).

## 2. High-Level System Diagram

```text
[Operator browser]
       │ HTTPS
       ▼
[Apache on Serversaurus] ─── docroot /home4/cogsaust/trust.cogsaustralia.org/
       │
       ├──▶ /admin/* ─── follows symlink ──▶ apex admin/<page>.php
       │                                          │
       │                                          └─▶ ops_db() → cogsaust_TRUST MySQL
       │
       └──▶ /_app/api/* ─ follows symlink ──▶ apex _app/api/<endpoint>.php
                                                     │
                                                     └─▶ getDB() → cogsaust_TRUST MySQL
```

Identical UX to apex `cogsaustralia.org/admin/`; just a different hostname for the same physical code.

## 3. Core Components

### 3.1 Symlink-served content

- **`/admin`** → apex's admin/. All 74 admin pages reachable. See apex `ARCHITECTURE.md §3.3`.
- **`/_app`** → apex's _app/. All API routes reachable from the trust host. Added during execution of the migration blueprint because admin JS fetches `/_app/api/*` via relative URL — without the symlink, login 404'd.

### 3.2 Local-repo content

The folder exists primarily as a deploy target so `deploy.sh` can sync any future trust-only content (e.g. a custom landing page, IP allowlist `.htaccess`). Empty by design as of 2026-05-28.

## 4. Data Stores

Same as apex (since the served code IS apex). See `cogsaustralia.org/ARCHITECTURE.md §4`.

- **`cogsaust_TRUST`** (MariaDB) — primary store.
- **Sessions:** PHP filesystem sessions. **Cookie scope currently host-only** — operator logs in once on apex AND once on trust (separate sessions). SSO deferred to a future blueprint when double-login becomes painful (see root TASKS.md backlog item).

## 5. External Integrations / APIs

Same as apex (the served code IS apex). See `cogsaustralia.org/ARCHITECTURE.md §5`.

## 6. Deployment & Infrastructure

- **Server:** Serversaurus cPanel.
- **Docroot:** `/home4/cogsaust/trust.cogsaustralia.org/`.
- **Deploy:** `./deploy.sh trust.cogsaustralia.org` from the operating-layer repo root. Currently no-op effectively (no local files to mirror except `ARCHITECTURE.md` + `README.md`).
- **Server-side symlinks** are NOT created by `deploy.sh`. They were created once manually during the migration. **If the server is ever rebuilt, both symlinks must be recreated** (single commands documented in `Claude_Code_CLI/projects/trust-subdomain-migration/blueprint.md`).

## 7. Security Considerations

- **Symlink integrity:** apex's `cogsaustralia.org/admin/` must never be physically moved — symlinks only (per root memory `feedback_admin_symlink`). Same constraint applies here transitively.
- **Auth:** operator-only, via PHP sessions on apex code path.
- **No CORS issues** for admin JS to API — both routes served from the same trust host via symlinks, so `/_app/api/*` is same-origin.
- **Apex URL still works** — both `https://cogsaustralia.org/admin/` and `https://trust.cogsaustralia.org/admin/` serve identically. Browser bookmarks on apex remain valid.
- **No IP allowlist / WAF** at this time (deferred per `trust-subdomain-migration` Q3 answer).

## 8. Development & Testing Environment

- **Local preview:** not meaningful — the site IS apex code via symlinks. Develop apex locally (`cd cogsaustralia.org && php -S localhost:8080`) and test admin there.
- **Production smoke check after any apex admin change:**

  ```bash
  ssh -i ~/.ssh/serversaurus cogsaust@shorty.serversaurus.com.au \
    'test -L /home4/cogsaust/trust.cogsaustralia.org/admin && echo "SYMLINK_OK" || echo "SYMLINK_MISSING"; test -L /home4/cogsaust/trust.cogsaustralia.org/_app && echo "_APP_OK" || echo "_APP_MISSING"'
  ```

  Expected: `SYMLINK_OK` + `_APP_OK`.

## 9. Future Considerations / Roadmap

- **SSO between apex and trust** — add `'domain' => '.cogsaustralia.org'` to `session_set_cookie_params()` in `cogsaustralia.org/admin/includes/ops_workflow.php`. Deferred per migration travel-sheet until double-login is annoying.
- **Outbound link migration** — flip mail templates, dashboard guide cards, `admin_url()` helper from `cogsaustralia.org/admin/...` to `trust.cogsaustralia.org/admin/...` as files are touched naturally. ~20–50 spots; deferred.
- **`_app/` symlink long-term decision** — keep, or refactor admin JS to use absolute apex API URLs and remove this symlink. Currently kept; tracked in root TASKS.md backlog.
- **IP allowlist / WAF** — if operator surface needs hardening separate from apex.

## 10. Project Identification

- **Project Name:** trust.cogsaustralia.org (operator subdomain — symlink-served)
- **Repository:** per-site git repo (SSH origin) — mostly empty
- **Primary Contact:** Thomas Cunliffe
- **Date of Last Update:** 2026-05-29

## 11. Glossary / Acronyms

See root [ARCHITECTURE.md §11](../ARCHITECTURE.md#11-glossary--acronyms) for shared terms. No site-specific additions at this time.