meos-dashboard/README.md

MeOS Dashboard

A web UI for the MeOS platform — wraps Forgejo API, vault browsing, and agent monitoring into one view.

Architecture

Browser → nginx (n97) → MeOS Dashboard (Next.js on port 3001)
                              ├── Forgejo API (repos, PRs, CI status)
                              ├── Filesystem API (vault browsing via server-side reader)
                              └── OpenClaw Gateway API (agent status, memory)

Stack

• Framework: Next.js 14 (App Router)
• Styling: Tailwind CSS (dark mode default, light mode toggle)
• Deployment: Node.js systemd service, reverse-proxied by nginx

Quick Start

1. Install dependencies

cd ~/vault/meos/dashboard
npm install

2. Configure environment

cp .env.local.example .env.local

Edit .env.local and add your Forgejo API token:

FORGEJO_API_URL=http://192.168.168.221:3000/api/v1
FORGEJO_TOKEN=your-token-here
VAULT_PATH=/home/sscoble/vault
OPENCLAW_API_URL=http://localhost:7477

3. Run in development mode

cd ~/vault/meos/dashboard
npm run dev

Or use the startup script:

~/vault/meos/start-dashboard.sh

Open http://n97:3001 (or http://192.168.168.97:3001).

4. Build for production

cd ~/vault/meos/dashboard
npm run build
npm run start

5. Install as a systemd service (production)

# First build the production bundle
cd ~/vault/meos/dashboard
npm run build

# Then install the service
sudo cp ~/vault/meos/meos-dashboard.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable meos-dashboard
sudo systemctl start meos-dashboard

Check status:

sudo systemctl status meos-dashboard

Routes

Route	Description
/	Dashboard overview — repos, recent zettels, agent status, quick actions
/vault	Vault browser — file tree, zettel viewer, search, graph view
/vault/[slug]	Direct zettel link
/presentations	Presentation repos and CI status
/agents	Department health, gateway status, memory info
/pipeline	CI/CD runs and recent commits

API Routes (internal, used by the frontend)

Route	Description
GET /api/forgejo/repos	List all repos
GET /api/forgejo/commits	Recent commits across repos
GET /api/forgejo/ci-runs	CI/CD workflow runs
GET /api/vault/list	List all vault .md files
GET /api/vault/read?path=	Read a zettel
GET /api/vault/search?q=	Search zettel content
GET /api/vault/recent	Last 5 modified zettels
GET /api/vault/graph	wiki-link graph JSON
GET /api/agent/status	Gateway health check
GET /api/agent/departments	Department statuses
GET /api/presentations/list	Presentation repos

Architecture Notes

• No authentication for MVP — runs on local network only
• No Docker — n97 is a low-power NucBoxG5, keep it lean
• Forgejo API is local at 192.168.168.221:3000 — proxied through Next.js API routes
• Vault access is direct filesystem reads from ~/vault/ — no database needed
• Port 3001 to avoid conflict with Forgejo on port 3000

Future Improvements

• Full D3.js graph visualization for vault wiki-links
• nginx reverse proxy with HTTPS (Let's Encrypt)
• Authentication (basic auth or OAuth proxy)
• Forgejo webhook integration (auto-refresh on push)
• Real-time agent status via WebSocket
• Zettel editing and creation from the UI
• OpenClaw Gateway integration for session management