AkurAI-Platform / ISA.md

Latest change f76bb4dada9e58a4f88f3f0d03d1cd203cdcfc28 - chore: keep gateway links EC2-local by Olafur Bui

---
project: AkurAI-Platform
task: EC2-local AkurAI platform gateway landing page
phase: complete
progress: 12/12
effort: E3
updated: 2026-06-26
---

# ISA - EC2-local AkurAI platform gateway

## Problem

The AkurAI services running on the EC2 VM are spread across systemd units,
nginx vhosts, and raw listening ports. There is no single gateway page that
answers what is on the VM, which URL reaches it, and whether the upstream is
active.

## Vision

Opening the platform gateway should feel like looking at the EC2 machine from
the edge inward: public vhosts, local upstream ports, systemd unit names, and
the few configured-but-down entries all line up in one quiet operational view.
The useful surprise is not decoration; it is that the page exposes the real VM
boundary clearly enough to avoid guessing.

## Out of Scope

No catalog of services that are not hosted on the EC2 VM. No external DNS
planning, no registrar work, no billing/provider inventory, and no broad
platform roadmap. The page may name public hostnames only when the matching
nginx/systemd/listener surface terminates on the EC2 VM.

## Constraints

- Use AkurAI-Framework as the web substrate.
- Keep the frontend no-build: HTML templates, CSS, native JS only.
- Keep inventory data in runtime files under `backend/`, not compiled into a
  binary.
- Deploy long-running runtime through systemd, not foreground/background shell.
- The only planning document is this PAI ISA.
- Current scope is EC2-local inventory only.

## Goal

Create `olibuijr/AkurAI-Platform` as an AkurAI-Framework app that lists EC2-local
AkurAI platform services and VM-local adjunct services, commit and push it, then
deploy it to the EC2 VM behind systemd/nginx without adding non-VM catalog items.

## Criteria

- [x] ISC-1: Project root contains an AkurAI-Framework app with `frontend/`, `backend/`, `data/`, and `akurai.toml`.
- [x] ISC-2: `ISA.md` declares EC2-local scope and anti-scope for non-VM services.
- [x] ISC-3: The runtime data lists `akurai-dns.service`.
- [x] ISC-4: The runtime data lists `akurai-mail-ui.service`.
- [x] ISC-5: The runtime data lists `akurai-idp.service`.
- [x] ISC-6: The runtime data lists `akurai-framework.service`.
- [x] ISC-7: The runtime data lists `akurai-vpn-site.service`.
- [x] ISC-8: The runtime data lists `rust-agent-gateway.service`.
- [x] ISC-9: The runtime data lists `rust-monitor.service`.
- [x] ISC-10: Anti: Runtime data contains no service whose `host_scope` is outside `ec2`.
- [x] ISC-11: The page renders locally through AkurAI-Framework and exposes the title `AkurAI Platform`.
- [x] ISC-12: The repository exists at `https://github.com/olibuijr/AkurAI-Platform`, has an initial commit pushed, and the VM service responds through its local nginx vhost.

## Test Strategy

| isc | type | check | tool |
|-----|------|-------|------|
| ISC-1 | file | project files exist | `test -d` / `test -f` |
| ISC-2 | file | scope text present | `rg` |
| ISC-3..9 | data | service ids present | `python3 -m json.tool` + `rg` |
| ISC-10 | data | every `host_scope` is `ec2` | `python3` JSON check |
| ISC-11 | live | local HTTP page includes title | `akurai serve` + `curl` |
| ISC-12 | git/deploy | GitHub repo and VM HTTP response | `gh repo view`, `git ls-remote`, `curl --resolve` |

## Features

| name | satisfies | depends_on | parallelizable |
|------|-----------|------------|----------------|
| PAI ISA | ISC-2 | VM scope decision | no |
| Runtime inventory data | ISC-3..10 | VM probe | yes |
| No-build frontend | ISC-1,11 | framework scaffold | yes |
| GitHub repository | ISC-12 | app files | no |
| EC2 deployment | ISC-12 | pushed repo, built binary | no |

## Decisions

- 2026-06-26: User clarified scope as "only list items on the ec2 vm"; the page will not catalog external services or perform external DNS work.
- 2026-06-26: Current AkurAI-Framework has enough support for this slice: static templates, `backend/page.json`, and the built-in HTTP server. No framework feature change is required unless verification exposes a gap.
- 2026-06-26: Deployed as `akurai-platform.service` on `127.0.0.1:8098` and added an nginx HTTP vhost for `platform.olibuijr.com`. External DNS/TLS were left out of scope per the EC2-only clarification.
- 2026-06-26: Removed the GitHub nav item from the rendered page because it is not an EC2-local item; repository metadata remains outside the gateway inventory.

## Changelog

- conjectured: The platform gateway would need a framework feature before it could ship.
  refuted by: Local and VM probes showed current AkurAI-Framework can serve routed templates with runtime JSON data.
  learned: This slice is an app/data deployment, not a framework internals change.
  criterion now: ISC-1 and ISC-11 encode the framework-app requirement.

## Verification

- ISC-1: file probe - `find . -maxdepth 3 -type f | sort` printed `./akurai.toml`, `./backend/page.json`, `./data/.gitkeep`, `./frontend/index.html`, and `./frontend/styles.css`.
- ISC-2: text probe - `rg -n ... ISA.md backend/page.json AGENTS.md` printed `ISA.md:53:- [ ] ISC-2: ... anti-scope for non-VM services` and `AGENTS.md:12: cloud-account, or non-VM services to the page`.
- ISC-3: data probe - `rg ... backend/page.json` printed `backend/page.json:49: "unit": "akurai-dns.service"`.
- ISC-4: data probe - `rg ... backend/page.json` printed `backend/page.json:25: "unit": "akurai-mail-ui.service"`.
- ISC-5: data probe - `rg ... backend/page.json` printed `backend/page.json:37: "unit": "akurai-idp.service"`.
- ISC-6: data probe - `rg ... backend/page.json` printed `backend/page.json:61: "unit": "akurai-framework.service"`.
- ISC-7: data probe - `rg ... backend/page.json` printed `backend/page.json:73: "unit": "akurai-vpn-site.service"`.
- ISC-8: data probe - `rg ... backend/page.json` printed `backend/page.json:85: "unit": "rust-agent-gateway.service"`.
- ISC-9: data probe - `rg ... backend/page.json` printed `backend/page.json:97: "unit": "rust-monitor.service"`.
- ISC-10: JSON probe - `python3 - <<'PY' ... all(s.get('host_scope') == 'ec2' for s in services)` printed `all_ec2 True`.
- ISC-11: local HTTP probe - `curl -fsS http://127.0.0.1:19098/api/health` printed `{"framework":"AkurAI-Framework","version":"0.1.0","status":"ok"}` and `rg` on the rendered HTML printed `<title>AkurAI Platform</title>`.
- ISC-12: repo/deploy probe - `gh repo view olibuijr/AkurAI-Platform --json name,url,visibility,defaultBranchRef` printed `{"defaultBranchRef":{"name":"master"},"name":"AkurAI-Platform","url":"https://github.com/olibuijr/AkurAI-Platform","visibility":"PRIVATE"}`; VM probe printed `service=active`, `upstream_health={"framework":"AkurAI-Framework","version":"0.1.0","status":"ok"}`, `nginx_title=<title>AkurAI Platform</title>`, and `nginx_inventory=akurai-platform.service`.
- Browser render probe: `npx -y agent-browser batch "open http://127.0.0.1:19098" "get title" "snapshot -i"` printed `AkurAI Platform`, heading `EC2 gateway for AkurAI services.`, required service headings, and port rows including `8098 / akurai-platform`.