Architecture Documentation

This directory contains architecture documentation for the Lucille project.

Documents

Affine Keys - Resource/tool lending via affine keys (design / discussion)
Delegations - Hierarchical write authority for jobs
HTTP Node Contract - Specification for external HTTP nodes that can execute Lucille jobs
VM Deploy (Docker + Self-hosted Runner) - Deployment architecture and rationale for the VM deployment approach
Scheduling - Agent-to-agent deferred work, run_at, pre-claim, marketplace result store and encryption
Marketplace - Marketplace design: auctions, reputation, result store (client public key, only supplier encrypts), pre-claim and credits; separate container
Module implementation synthesis - How Lucille synthesizes, validates, stores, and promotes new implementations for missing instincts
Thoughts - Architecture notes on the Thoughts feature
Instincts - Known vs agentic instincts, signature hash, registry
Job hierarchy - Current assistant flow: single scheduler entry job fans out into user-scoped assistant work
Assistant next step - Historical per-user assistant design kept for reference only
Open loops - Surfacing layer for unresolved items (ideas, tasks, lapsed check-ins, commitments, fuzzy intentions); channels, scoring, and the open contextual-surfacing question
Stewardship - Triage → drafted plan → critic-gated routing → steward loop → outcome eval. The path from "Lucille captured something" to "Lucille did the work or proved she couldn't" — six task kinds, push-based review, deterministic outcome scoring
Reply guarantee - Every inbound turn that expects a reply yields one user-visible signal (reply / deliberate reaction / deferred); generic chat-turn mechanism + send choke + per-frontend on_silent fallback (Telegram orchestrator handoff, Nivi guided clarification)

High-Level Architecture

See ../architecture.md for the overall system architecture, design principles, and vision.

Quick Reference

Backend: FastAPI + async SQLAlchemy + Supabase Auth
Worker: Polls backend for jobs, executes them, reports results
Web: Next.js app that proxies API calls to backend
Deployment: Docker Compose on VM with self-hosted GitHub Actions runner