Portal Documentation

Living documentation for the Agentic Hub β€” portal features, workflows, entities, architecture, and design decisions.

πŸ‘‹ Welcome

This is the canonical reference for everything in the Adrian Portal (hub.adrian.my). It covers every entity, API endpoint, design decision, and architectural pattern.

Why this exists: Design decisions and rationale get lost when task folders are archived and context is compressed. These docs persist the why, not just the what.

🫁 The Two Loops

The Hub breathes through two complementary loops β€” one creates, one learns. Together they form a self-improving system.

πŸ”¨ Creation Loop (剡造) β€” exhale
🧭 Vision β€” WHY?
↓
🌳 Nexus β€” WHERE?
↓
πŸ”΄ Problems β€” WHAT HURTS?
↓
πŸ“ Projects β€” BUILD WHAT?
↓
πŸ“‹ Tasks β€” DO IT
FEEDS
🫁
FEEDS
πŸ’‘ Insight Loop (升華) β€” inhale
β˜€οΈ Raw Content β€” WHAT CAME IN?
↓
πŸ§ͺ Distillery β€” KEEP WHAT?
↓
🧠 Knowledge Base β€” STRUCTURE
↓
πŸ“– Wiki β€” PUBLISH

πŸ“¦ Portal Entities

The portal manages 15 entities across D1 (Cloudflare's serverless SQL). Each entity has its own schema, API, and lifecycle.

CORE πŸ“‹ Task

Work units with full lifecycle. The strategic tech tree and backlog. IDs like A66, d-prefix for drafts.

ACTIONABLE πŸ“₯ Feedback

Proactive inbox items. Clara processes them. Lifecycle: open β†’ processed. Human-only park/archive.

PERMANENT πŸ’¬ Comment

Append-only audit trail on entities. Like GitHub issue comments. Never deleted.

HYBRID πŸ“Š Report

D1 metadata + static HTML. Two modes: article and slide deck. Published via skill.

REALTIME πŸ’­ Message

Agent chatroom channels with SSE streaming. #dev channel for session tracking.

EXECUTION πŸš€ Remote Job

Bifrost job queue. Types: session, research, workflow, autopilot. Real-time SSE output.

✨ Portal Features

Guides to every page in the portal UI β€” what it does, how to use it, and how it connects to the rest of the system.

✨ Features Overview

All portal pages, cross-cutting features, and operating modes.

πŸ“Š Dashboard

ForceTree graph, Backlog view, Lane view β€” the strategic bird's-eye view.

πŸ“₯ Inbox

Compose, capture, and triage. The entry point for all work.

πŸš€ Remote Jobs

Bifrost job queue with real-time SSE streaming output.

πŸŒ‰ Bifrost

The execution bridge β€” submit jobs from the portal and Bifrost runs them autonomously via Claude or Gemini CLI.

πŸŒ‰ Bifrost Overview

Architecture, key concepts, and API endpoints for the execution bridge.

▢️ Getting Started

Submit your first job β€” three entry points explained step-by-step.

πŸ“¦ Job Types

Session, research, workflow, clara, autopilot β€” when to use each.

πŸ€– LLM Providers

Claude vs Gemini β€” models, effort budgets, and backend switching.

πŸ”„ Job Lifecycle

Status flow, timeouts, rate limits, auto-retry, and scheduled jobs.

πŸ”§ Troubleshooting

Error states, Gemini detection, common issues, and recovery playbook.

⚑ Workflows & Commands

32 slash commands organized by the Two Loops β€” from vision alignment to knowledge distillation.

⚑ Workflows Overview

Complete command reference with categories, composability layers, and decision flow.

🧹 Clara

Dispatch agent β€” sweep, tidy, archive, focus, align.

πŸ“‹ Task Lifecycle

Start, save, done, archive β€” the full task journey.

πŸ“ˆ Tracking

Logging, status, velocity, wrap-up β€” observability layer.

πŸ—οΈ Architecture

The portal is a Cloudflare Pages app backed by D1 (serverless SQLite). 18 API endpoints, React front-end, dual-loop design.

πŸ—οΈ System Architecture

Deployment model, API patterns, design principles, and the local-first philosophy.

πŸ—ΊοΈ Entity Mindmap

Interactive SVG visualization of all portal entities and their relationships.

⚑ Quick Reference

API Endpoints (18)

Endpoint Methods Purpose
/api/tasks GET/POST/PATCH/DELETE Task lifecycle + tech tree
/api/feedback GET/POST/PATCH/DELETE Actionable inbox items
/api/comments GET/POST Append-only audit trail
/api/reports GET/POST/PATCH/DELETE Report metadata registry
/api/messages GET/POST/PATCH/DELETE Agent chatroom channels
/api/remote-jobs GET/POST/PATCH/DELETE Bifrost job queue
/api/velocity GET/POST/DELETE Time tracking entries
/api/logs GET/POST/DELETE Session log entries
/api/dashboard GET Aggregated dashboard stats
/api/projects GET/POST/PATCH/DELETE Project metadata + grouping
/api/problems GET/POST/PATCH/DELETE Problem registry (Creation Loop)
/api/nexus GET/POST/PATCH Vision tree nodes
/api/distill GET/POST/PATCH Distillery pipeline items
/api/learnings GET/POST Knowledge items from Insight Loop
/api/preferences GET/PATCH User preferences + settings
/api/workflow-usage GET/POST Workflow invocation tracking (CE8)

Key Concepts

Concept Location What
Two Loops Architecture Creation Loop (剡造) builds. Insight Loop (升華) learns. Together they breathe.
Local-first Agents β†’ files Agents write local files. D1 is the portal's read layer. Clara syncs.
Dual-write Logs, velocity POST to API + write local .md. Both are sources of truth for different consumers.
Soft-delete All D1 tables Never DELETE. PATCH status to archived. History is preserved.
CLI > raw API Portal CLI portal command handles auth, URLs, error formatting. 7 command groups.
Portal Documentation v3 Β· April 2026 Β· Back to Portal