AkurAI-Platform / ISA.md

Latest change 27dec3641b699076dd38e17d7e89e5b88a93b0b4 - feat: add EC2 platform gateway by Olafur Bui

---
project: AkurAI-Platform
task: EC2-local AkurAI platform gateway landing page
phase: execute
progress: 11/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`.
- [ ] 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.

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