Menu
Public repository / f9ad97f6d8275ebdd13ec7823f9186bdad2c744a
AkurAI-Platform / ISA.md
Latest change f9ad97f6d8275ebdd13ec7823f9186bdad2c744a - feat: present AkurAI source-linked platform 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 need a public-facing project page,
not an operator inventory. The page should connect live deployments to source
repositories and show measured process memory without making the VM mechanics
the main story.
## Vision
Opening the platform gateway should feel like entering the AkurAI open-source
project: live services, GitHub repositories, and memory footprint in one clean
directory. VM details remain available only where they explain measurement or
scope.
## 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. GitHub repository links are allowed as source metadata for
VM-hosted entries.
## Constraints
- Use AkurAI-Framework as the web substrate.
- Keep the frontend no-build: HTML templates, CSS, native JS only.
- Keep application, source-link, and memory 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 presents
EC2-local AkurAI platform deployments, source repositories, and measured memory;
commit and push it, then deploy it to the EC2 VM behind systemd/nginx without
adding non-VM catalog entries.
## 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.
- 2026-06-26: `http://platform.olibuijr.com/` initially failed because public DNS had no A record. Added `platform.olibuijr.com A 3.94.46.219` in 1984dns and mirrored it into the EC2-local AkurAI DNS zone.
- 2026-06-26: Removed `pi.olibuijr.com` / Bui Pi Bridge from the EC2 VM on user request: deleted nginx vhost, Certbot certificate, and `/opt/bui-pi-bridge`, then removed it from the gateway inventory.
- 2026-06-26: Reframed the rendered page from an operator inventory to an open-source project directory. The live entries remain EC2-scoped, while GitHub repository links are shown as source metadata.
- 2026-06-26: Removed the visible "AI-written Rust code is the future of programming" style copy and replaced it with direct project/source/memory language.
## 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`.
- Public URL repair probe: DNS creation printed `created platform.olibuijr.com A -> 3.94.46.219 (entry 6285509)`; final plain URL probe printed `default=3.94.46.219` and `HTTP/1.1 200 OK` for `http://platform.olibuijr.com/`.
- Bui Pi Bridge removal probe: VM command printed `removed-enabled-vhost`, `removed-available-vhost`, `removed-certbot-cert`, `removed-opt-bui-pi-bridge`, `nginx: configuration file /etc/nginx/nginx.conf test is successful`, `opt_left=no`, and `cert_left=0`.
- Source-first landing page probe: `curl http://platform.olibuijr.com/` printed `Live services tied to source repos.`, GitHub links including `https://github.com/olibuijr/AkurAI-Platform`, memory references including Keycloak/Grafana/CoreDNS, and no matches for the removed copy (`future of programming`, `AI-written`, `Listening ports`, `Nginx vhosts`, `topology`).
- Browser helper note: `agent-browser` still fails against `http://platform.olibuijr.com` with `net::ERR_BLOCKED_BY_CLIENT`; Chromium headless screenshots were captured instead for desktop and mobile layout checks.