๐๏ธ System Architecture
Two Loops architecture, deployment model, API patterns, design principles, and the local-first philosophy. Updated April 2026.
Stack Overview
| Layer | Technology | Location |
|---|---|---|
| Frontend | React 19 + Vite 7 | Cloudflare Pages (static) |
| API | Cloudflare Pages Functions | functions/api/*.js |
| Database | Cloudflare D1 (SQLite) | agentic-hub-db |
| Execution | Node.js Express (PM2) | apps/bifrost-api/ |
| CI/CD | Manual (wrangler pages deploy) |
From apps/portal/ directory |
Deploy is manual: Git push does NOT auto-deploy. After pushing portal changes, run:
npx wrangler pages deploy public/ --project-name adrian-agentic-hub-portal from
apps/portal/.
Key Concepts
Local-First, D1 as Read Layer
Agents write local files (always works offline). D1 is the portal's read layer for the UI. Clara is the sync bridge โ she reads local files and POSTs to D1 APIs.
Agent writes file
โ
Clara reads locally
โ
Clara POSTs to D1
โ
Portal reads D1
Dual-Write Pattern
Logs and velocity use dual-write: POST to D1 API AND write local .md file. The local file is the
agent-readable cache; D1 is the portal's source of truth.
D1 POST requires
date: The /api/logs POST requires
date, workspace, AND content. Missing date returns 400
silently. Always include date: "YYYY-MM-DD" in the body.
Soft-Delete Everywhere
No D1 record is ever physically deleted. Status is PATCHed to an end-state (e.g., archived,
done). This preserves all history for velocity analysis, audit trails, and debugging.
โฑ๏ธ Velocity Tracking
Every agent session tracks time via /api/velocity. Sessions are measured in minutes, not
hours. The velocity ledger records: date, workspace, task, time range, net minutes, and notes.
| Metric | Location | Purpose |
|---|---|---|
| Session log | ws/logs/YYYY-MM-DD-{convId8}.md + /api/velocity |
Per-session time tracking |
| Daily log | ws/logs/YYYY-MM-DD-*.md + /api/logs |
What was accomplished |
| Ongoing | ws/ongoing.md |
Active tasks across all workspaces |
๐ค Agent System
| Agent | Role | Workspace | Status |
|---|---|---|---|
| Akira | Architect + Builder | Agentic (Hub) | Active |
| Clara | Secretary + PM | Agentic (Hub) | Active |
| mipos-dev-agent | Builder | Dev | Active |
| adrian-life-agent | Coach | Life | Scaffolded |
| mipos-chief-agent | Strategist | Work | Scaffolded |
Dual-Agent Hub: The Agentic Hub uniquely houses two agents. Akira designs,
builds, and evolves the system. Clara processes brain dumps, classifies tasks, manages
priorities, and maintains clarity. Clara has 5 modes: inbox, sweep, archive, focus, align.
Clara's Modes
| Mode | Command | What It Does |
|---|---|---|
| Inbox | /clara |
Process inbox โ classify โ route to workspaces. Pulls from portal feedback + local inbox. |
| Sweep | /clara sweep |
Process open feedback items. Clara marks as processed with notes. |
| Tidy | /clara tidy |
Scan for stale/done tasks, sync ongoing โ tech tree. |
| Focus | /clara focus |
Pick highest-priority task, load context, suggest next action. |
| Align | /clara align |
Weekly priority review. Update priorities.md. |
๐ API Middleware Pattern
All API files use the shared _utils.js middleware (apiRouter) which provides:
| Feature | What |
|---|---|
| Auth | checkAuth โ validates API key header |
| CORS | Handles preflight and cross-origin headers |
| Error handling | Catches and formats errors consistently |
| Response wrapping | Uses _httpStatus to avoid collision with DB status columns |
Integration tests: 36-test suite at
portal/tests/test-api.ps1 covers all
endpoints.
๐ Directory Structure
apps/portal/ โโโ functions/api/ API endpoints (Cloudflare Pages Functions) โ โโโ _utils.js Shared middleware (apiRouter, checkAuth, CORS) โ โโโ tasks.js Task CRUD โ โโโ feedback.js Feedback CRUD + state transitions โ โโโ comments.js Append-only comments โ โโโ reports.js Report metadata registry โ โโโ messages.js Channel messages + SSE โ โโโ remote-jobs.js Job queue + heartbeat โ โโโ velocity.js Time tracking โ โโโ logs.js Session logs โ โโโ dashboard.js Aggregated stats โ โโโ preferences.js User preferences โ โโโ projects.js Project metadata + grouping โ โโโ problems.js Problem registry (Creation Loop) โ โโโ nexus.js Vision tree nodes โ โโโ distill.js Distillery pipeline items โ โโโ learnings.js Knowledge items โ โโโ workflow-usage.js Workflow invocation tracking โโโ public/ Static assets (built React app) โ โโโ reports/ Static HTML reports โโโ src/ React source (Vite) โ โโโ components/ React components โ โโโ services/api.js API client functions โโโ migrations/ D1 schema โโโ tests/ Integration test suite
๐ Key Decisions Log
| Date | Decision |
|---|---|
| Mar 6 | API-only for D1 access โ no CLI tools. Agents use fetch. |
| Mar 6 | D1-primary, local-cache โ D1 is source of truth. Local files are agent caches. |
| Mar 9 | Portal V2 promoted to root โ React 19 + Vite 7. V1 archived at /v1/. |
| Mar 10 | Bifrost Node.js API โ replaced PS polling. PM2-managed, SSE streaming, auto-restart. |
| Mar 10 | API middleware (_utils.js) โ centralized auth, CORS, response wrapping.
-400 lines. |
| Mar 14 | Entity Architecture โ comments table split into Comment (append-only) + Feedback (lifecycle). |
| Mar 14 | Bifrost auto-resume โ rate-limited jobs auto-retry. Portal shows countdown timer. |
| Mar 21 | Portal CLI โ portal npm-linked CLI. 7 command groups: task, log, velocity,
report, feedback, comment, job. |
| Mar 30 | MCP removed โ Portal MCP redundant with CLI. CLI is primary interface for agents. |
| Apr 1 | Problems as first-class entity โ /api/problems endpoint. AC13 drives
Creation Loop. |
| Apr 12 | Two Loops (A160) โ Dual-loop architecture formalized. Creation (ๅต้ ) + Insight (ๅ่ฏ). Cortex brand retired. |
| Apr 13 | Docs standalone โ Docs moved to apps/agentic-hub-docs/ submodule. Wiki
(Fumadocs) retired. v3 with componentized sidebar. |