# Juliaz System

> Foundational knowledge about the juliaz_agents multi-agent system architecture. ALWAYS trigger this skill when the conversation involves ANY component of Julia's agent ecosystem — orchestrator, bridge, cowork-mcp, OpenClaw, frontend, backend, ADHD agent, julia_medium_agent, or thesis workspace. Also trigger when Raphael asks 'where is X', 'how does X work', 'what connects to what', or any architectural/navigation question about the system. This is the map of the entire codebase and how the pieces fit together.

- Skill: `abzhaw/juliaz-system` (Agent Skill)
- Install (CLI): `npx skillmds@latest add abzhaw/juliaz-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abzhaw/juliaz-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: abzhaw (https://skillmd.com/u/abzhaw)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/abzhaw/juliaz-system

---


# juliaz-system — Architecture & Navigation

> You are working on **juliaz_agents** — Raphael's multi-agent platform for his master's thesis on autonomous AI collaboration.

## Mental Model

```
Raphael (human) → Antigravity (IDE agent / builder) → Julia (the product being built)
```

- **Antigravity** = the AI in the IDE (Claude Code / Cowork) that builds Julia
- **Julia** = the multi-agent system being built
- **OpenClaw** = communication gateway (Telegram, WhatsApp, etc.)

## 3-System Architecture

### `julia/` — User-System (the product)

| Component | Location | Port | Stack | Role |
|-----------|----------|------|-------|------|
| **Frontend** | `julia/frontend/` | 3002 | Next.js 15 + Tailwind + Framer Motion | Dashboard UI with its own AI chat (GPT-4o via Vercel AI SDK) |
| **Bridge** | `julia/bridge/` | 3001 | Express + MCP (streamable HTTP) | Message hub connecting agents ↔ UI. Queue stored in `data/queue.json` |
| **Backend** | `julia/backend/` | 3000 | Express + Prisma + PostgreSQL (Docker) | REST API for persistence: tasks, memories, letters, logs, usage, updates |
| **Orchestrator** | `julia/orchestrator/` | — | Claude Haiku (primary) + GPT-4o (fallback) | Julia's brain. Polls bridge every 5s, generates replies, manages memory |
| **Cowork MCP** | `julia/cowork-mcp/` | 3003 | MCP server wrapping Anthropic API | Claude delegation: 6 tools (claude_task, multimodal, code_review, summarize, brainstorm, status) |
| **OpenClaw** | `julia/openclaw/` | — | `openclaw` CLI (npm global) | Telegram gateway. Forwards messages to bridge via `julia-relay` skill |

### `meta/` — Meta-System (development & maintenance)

| Component | Location | Schedule | Role |
|-----------|----------|----------|------|
| **ADHD Agent** | `meta/agents/adhd-agent/` | every 4h (LaunchAgent) | System hygiene: scans for duplicate skills, dead agents, orphaned configs |
| **Health Checker** | `meta/agents/health-checker/` | every 15min | Service monitoring, self-healing, escalation tiers |
| **Security Agent** | `meta/agents/security-agent/` | daily 07:00 | Security scanning: ports, credentials, dependencies, Docker |
| **Docs Agent** | `meta/agents/docs-agent/` | every 12h | Documentation drift detection |
| **Task Manager** | `meta/agents/task-manager/` | every 6h | Task queue integrity, stale task detection |
| **Architecture Agent** | `meta/agents/architecture-agent/` | every 6h | System topology scanning, neural map generation |

### `thesis/` — Thesis-System (research & academic)

| Directory | Purpose |
|-----------|---------|
| `thesis/agents/thesis-agent/` | Academic writing partner (reads system, writes thesis) |
| `thesis/latex/` | LaTeX thesis source |
| `thesis/documentation/` | Project logs |

### Cross-system & config (root level)

| Directory | Purpose |
|-----------|---------|
| `shared-findings/` | Cross-agent communication backbone |
| `meta/docs/` | System documentation, agent cards, planning prompts |
| `.superpowers/` | Development framework (brainstorming, TDD, plans) |

## Message Flow (Telegram → Julia → Reply)

```
Telegram user sends message
  → OpenClaw gateway receives it (ws://127.0.0.1:18789)
    → OpenClaw POSTs to bridge: POST http://localhost:3001/incoming
      → Bridge stores in queue.json (state: pending)
        → Orchestrator polls via MCP: telegram_get_pending_messages (state → processing)
          → Orchestrator generates reply (Claude Haiku → GPT-4o fallback)
            → Orchestrator calls MCP: telegram_send_reply (state → replied)
              → OpenClaw polls GET /pending-reply/:chatId
                → OpenClaw delivers to Telegram
```

## Key Patterns & Conventions

### Agent Definition Files
Each agent directory follows this convention:
- `SOUL.md` — Core identity, personality, values, boundaries
- `IDENTITY.md` — Name, creature type, vibe, emoji
- `TOOLS.md` — Available tools and environment config
- `AGENTS.md` — Behavioral playbook, memory patterns, group chat rules
- `HEARTBEAT.md` — Scheduling, health checks, reporting cadence
- `HEURISTICS.md` — Learned rules from past incidents
- `MEMORY.md` — Persistent context across sessions
- `USER.md` — Info about the user (Raphael)

### Tool Definition Patterns
- **Anthropic format** (orchestrator, cowork-mcp): `{ name, description, input_schema }` with JSON Schema
- **OpenAI format** (frontend chat): `{ function: { name, description, parameters } }`
- **MCP tools** (bridge): Defined via `server.tool(name, schema, handler)`

### Error Handling
- **Graceful fallback**: Claude Haiku → GPT-4o (orchestrator)
- **Exponential backoff**: Consecutive errors trigger increasing delays (capped 55s)
- **Rate limiting**: Honors `Retry-After` header from Anthropic
- **Fire-and-forget**: Memory capture and letter generation never crash main loop
- **Timeouts**: 30s per API call with AbortController

### Memory System
- **Short-term**: In-memory conversation history (20 messages = 10 turns per chat)
- **Long-term**: Backend PostgreSQL (memories, letters, logs, tasks)
- **Memory extraction**: gpt-4o-mini categorizes moments as STORY, FEELING, MOMENT, WISH, REFLECTION
- **Letter generation**: Daily physical letters via Lob.com using GPT-4o + seed file + recent memories

### Configuration
- **Environment**: `.env.example` (template), `.env.secrets` (live keys — NEVER commit)
- **Process manager**: PM2 via `ecosystem.config.js` (prod) / `ecosystem.dev.config.js` (dev)
- **Docker**: Only backend runs in Docker (PostgreSQL + Express API)
- **MCP config**: `.mcp.json` for bridge connection

## File Location Quick Reference

When Raphael asks "where is X", use this:

| Looking for... | File(s) |
|----------------|---------|
| Julia's personality/prompt | `julia/orchestrator/src/prompt.ts` |
| Tool definitions (orchestrator) | `julia/orchestrator/src/tools.ts` |
| Claude API client | `julia/orchestrator/src/claude.ts` |
| GPT-4o fallback client | `julia/orchestrator/src/openai.ts` |
| Main polling loop | `julia/orchestrator/src/index.ts` |
| Memory extraction logic | `julia/orchestrator/src/memory-keeper.ts` |
| Letter generation | `julia/orchestrator/src/letter-scheduler.ts` + `julia/orchestrator/src/lob.ts` |
| Bridge MCP tools | `julia/bridge/src/index.ts` |
| Bridge message queue | `julia/bridge/data/queue.json` |
| Cowork MCP tools | `julia/cowork-mcp/src/index.ts` |
| Frontend chat endpoint | `julia/frontend/app/api/chat/route.ts` |
| Dashboard page | `julia/frontend/app/page.tsx` |
| DevOps API route | `julia/frontend/app/api/devops/route.ts` |
| Backend REST API | `julia/backend/src/index.ts` |
| Database schema | `julia/backend/prisma/schema.prisma` |
| Docker setup | `julia/backend/docker-compose.yml` |
| PM2 configs | `ecosystem.config.js`, `ecosystem.dev.config.js` |
| OpenClaw relay skill | `julia/openclaw/skills/julia-relay/` |
| OpenClaw troubleshooting | `julia/openclaw/skills/openclaw-troubleshoot/` |
| System overview (non-technical) | `meta/docs/agent_system_overview.md` |
| Agent cards | `meta/docs/agent_cards/` |
| Ambient agents | `meta/agents/` |
| Thesis research | `thesis/research_papers/` |
| Thesis drafts | `thesis/drafts/` |
| Thesis agent | `thesis/agents/thesis-agent/` |

## Known Pain Points

These are real issues in the codebase — reference them when relevant:

1. ~~**Hardcoded Mac paths** in orchestrator tools~~ (FIXED: now uses `/Users/raphael/juliaz_agents/julia/openclaw/skills/email-aberer`)
2. **Tool definition duplication** between orchestrator and frontend (both define similar tools separately)
3. **No pagination** on any backend GET endpoint (returns entire table)
4. **Bridge queue grows unbounded** — no pruning of old replied messages
5. **Memory lost on restart** — in-memory conversation history clears before DB save
6. **Cowork MCP defaults to Haiku** despite being intended for complex delegation
7. **No structured logging** — sparse console.log, no log levels
8. **No tests visible** — no test files or CI/CD pipeline (except backend has Vitest configured)
9. **No authentication** on any endpoint (frontend chat, backend API, bridge)
10. **Silent content truncation** — cowork-mcp silently drops content over 25K chars

## Backend Database Tables

| Table | Key Fields |
|-------|-----------|
| `task` | title, priority, dueDate, completed |
| `memory` | chatId, category, content, originalText |
| `letter` | content, status (DRAFT/SENT), lobId, sentAt |
| `log` | level, source, message |
| `usage` | model, promptTokens, completionTokens, totalTokens |
| `update` | title, content, type |

## Bridge MCP Tools

| Tool | Purpose |
|------|---------|
| `telegram_get_pending_messages` | Fetch & mark messages as processing |
| `telegram_send_reply` | Queue a reply (with optional messageId) |
| `telegram_bridge_status` | Status snapshot |
| `telegram_receive` / `telegram_send` | Compatibility aliases |
| `bridge_health` | Detailed peer reachability |