Kevin Platform Architecture
1 / 53
S001 — Bus-Driven Architecture (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | ServiceBase publishes identity + heartbeat to MQTT on boot. 1 - ServiceBase Initialization ServiceBase.__init__ daemon/src/service_base.py:351 service_name version _resolve_role _VALID_ROLES _get_role_from_config role.json _environment KEVIN_ENVIRONMENT dev test prod service_name,… 2 - MQTT Connection and Identity Publishing connect_and_run aiomqtt.Client hostname port _emit kv/service/{service}/identity retain=True QoS 1 MQTT client 3 - Heartbeat Loop _heartbeat_loop asyncio.sleep heartbeat_interval_s _emit _emit kv/service/{service}/heartbeat QoS 1 heartbeat payl… 1. ServiceBase.__init__ initia… 2. _resolve_role determines th… 3. _environment fetches the en… 4. connect_and_run establishes… 5. _emit publishes retained id… 6. _heartbeat_loop starts publ… Identity Payload {"service": "daemon", "version": "2026-05-23T074530Z-a3f8e2c", "role": "owner", "status": "starting", "environment": "de… Heartbeat Payload {"service": "daemon", "version": "2026-05-23T074530Z-a3f8e2c", "role": "owner", "status": "healthy", "uptime_seconds": 3… The source does not show any implementation for VersionVerifier or AutoHealer, so they are not included in the dataflow diagram. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
S002 — Build Versioning (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Immutable {ISO}Z-{git_short} version per build. 1 - Version Generation generate_version.py get_git_commit() generate_version() write_version_file() 2 - Embedding in Services PyInstaller (daemon.spec) daemon.spec npm build script package.json:build inject-version.js electron-builder electron-builder.yml version string 3 - Publishing to Bus ServiceBase startup() _load_build_version() mqtt.publish() 1. generate_version.py ge… 2. Writes version to .rel… 3. Embeds version in daem… 4. npm build script injec… 5. electron-builder uses… 6. ServiceBase loads vers… 7. Publishes identity mes… Version string example 2026-05-23T074530Z-a3f8e2c MQTT identity message {"service": "daemon", "version": "2026-05-23T074530Z-a3f8e2c", "role": "worker", "timestamp": 1684800000, "status": "hea… 5 of 9 identifiers appear only in design docs, not in code — this shows SPECIFIED behaviour, not verified implementation. The build script generates the version string once per build. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
S003 — Port Management (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Canonical port table with prod/test/release offsets. 1 - PORT ALLOCATION - Port allocation and management daemon/config/services.yaml port_pool services daemon/src/main.py __init__ _find_available_port Environment Variables KEVIN_PORT_DAEMON KEVIN_TEST_PORT_DAEMON KEVIN_RELEASE_PORT_DAEMON port configura… environment va… 1. Load port configuration from serv… 2. Set environment variables for eac… 3. Initialize services with their re… 4. Check if the allocated port is av… 5. Start services using the assigned… Port Configuration in services.yaml services: daemon: port: 8001 test_port: 18001 release_port: 28001 Environment Variable Example export KEVIN_PORT_DAEMON=8001 export KEVIN_TEST_PORT_DAEMON=18001 export KEVIN_RELEASE_PORT_DAEMON=28001 The source does not show any interaction with external dependencies or third-party services beyond environment variables. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
S004 — Config is Opinion (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Domain language in config, not code. 1 - CONFIG LOADING - Loading configuration CLI Args --role=manager --domain=healthcare Environment Variables KEVIN_ROLE=manager KEVIN_DOMAIN=healthcare User Config File ~/.kevin/config.json Project Config File project_root/config.json role domain 2 - DATA MODELING - Using generic field names load_config() config.py:100 Note Model models/note.py subject_id content config 3 - PROMPT GENERATION - Configuring prompts generate_note() Prompt Config config.yaml note_generation_prompt prompt 1. Parse CLI args 2. Load environment varia… 3. Read user config file 4. Read project config fi… 5. Initialize Note model… 6. Load prompt configurat… 7. Generate note using co… User Config JSON { "role": "manager", "domain": "healthcare" } Prompt Config YAML note_generation_prompt: "You are a clinical psychologist. Analyze the note and provide assessment." 9 of 10 identifiers appear only in design docs, not in code — this shows SPECIFIED behaviour, not verified implementation. Configuration files are prioritized in a specific order, with CLI args taking precedence. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
S005/S006/S007 — MQTT / Errors / Roles (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Topic schema, error handling, role-based coordination. MQTT Bus Patterns ServiceBase startup() _heartbeat_loop() VersionVerifier _alert_mismatch() start() AutoHealer _publish_audit_log() start() identity messa… heartbeat mess… Role-Based Coordination ~/.kevin/role.json ConfigClient determine_role() init_config_client() ConfigServer get_rules() role configura… rule request 1. ServiceBase publishes identity an… 2. VersionVerifier subscribes to ser… 3. AutoHealer subscribes to mismatch… 4. ConfigClient determines role from… 5. ConfigServer provides rules based… Identity Message Payload {"service": "daemon", "version": "2026-05-23T074530Z-a3f8e2c", "role": "owner", "timestamp": 1715813520, "status": "healthy"} Mismatch Alert Payload {"service": "daemon", "actual_version": "2026-05-20T...-old", "expected_version": "2026-05-23T...-new", "timestamp": 1715813520, "reason": "version drift detected"} 9 of 9 identifiers appear only in design docs, not in code — this shows SPECIFIED behaviour, not verified implementation. ServiceBase and AutoHealer publish messages with QoS 1. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Daemon Core — Boot & Event Dispatch (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | main.py → ServiceManager → EventBus → MQTT/SSE fanout. 1 - BOOTSTRAP - Daemon Initialization main.py python -m daemon setup_env(daemon_root) lan_autosetup(daemon_root) _bootstrap.py setup_env _mqtt_reachable lan_autosetup daemon startup… 2 - SERVICE MANAGEMENT - Core Services ServiceManager init_mesh_api get_event_bus load_plugins event_bus.py bus.publish() kv/events/# _lvc_writer_loop mesh API initi… 3 - EVENT DISPATCH - MQTT/SSE Fanout EventBus publish() mount_mqtt(mqtt_client) _lvc_writer_loop MQTT Broker localhost:1883 kv/events/# event publishi… 1. Start daemon with command 2. Load environment variables 3. Auto-setup LAN configuration 4. Initialize mesh API and eve… 5. Load core services and plug… 6. Publish events to MQTT brok… Sample Event Payload { "e": "holon:queued", "ts": 1672531200.0, "id": "uuid8-1234", "holon_id": "...", "to": "flynn" } MQTT Topic Structure kv/events/holon:queued kv/events/job:progress kv/events/ai:approval The MQTT broker connection is checked during bootstrap. If not reachable, the daemon operates in offline mode. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Walt — LLM Fabric Proxy (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | OpenAI-compatible facade · Groq/Anthropic/Gemini/Ollama · Stripe-metered. 1 - API REQUEST HANDLING FastAPI server POST /v1/messages GET /health GET /v1/models JWT verifier verify_jwt() startup_jwt_verification() request 2 - MODEL ROUTING Model router route() _provider_for_model() MODEL_PRICES cost_usd() tier_enforcement model request 3 - PROVIDER INTEGRATION Anthropic API anthropic_provider Gemini API gemini_provider Groq API groq_provider Ollama API ollama_provider OpenAI API openai_provider model request API response 1. FastAPI server receives a request 2. JWT verifier verifies the request 3. Model router decides which provid… 4. Provider API is called with the m… 5. Provider returns the API response Stripe webhook event payload { "type": "customer.subscription.created", "data": { "object": { "id": "sub_1234567890", "status": "active", "items": { "data": [ { "price": { "product": "prod_abcdefg" } } ] } } } } JWT token payload { "iss": "https://example.com/issuer", "sub": "user1234567890", "aud": "https://example.com/audience", "exp": 1672531200, "iat": 1672444800, "jti": "abcdefg" } The JWT verification is critical for security and must be enabled in production. Stripe integration handles subscription events but does not verify webhook signatures yet. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Grant — Authorization Decision (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Token verify → capability trie → entitlement → allow/deny + audit. 1 - AUTHORIZATION CHECK get_subject __init__.py GET /api/vault/{mount}/{path:path} resolve subject from request headers check daemon/src/grant/__init__.py:48 async def check(subject: str, resource: str, op: str) -> bool: check if subject can perform op on resource reg_keys table daemon/src/grant/accounts.py:107 INSERT OR IGNORE INTO reg_keys (key_hash, account_class, created_at) VALU… registration keys storage subject resource 2 - ACCOUNT CLASS RESOLUTION resolve daemon/src/grant/account_class.py:30 def resolve(account_class: str, *, _config: dict | None = None) -> dict: map account_class to feature bundle account_classes.json daemon/config/account_classes.json tier: free | pro | institutional feature keys available per account class account_class 3 - ENTITLEMENT EVALUATION entitlements_for daemon/src/grant/accounts.py:58 def entitlements_for(account_class: str) -> tuple[str, ...]: return feature keys for account class permissions table daemon/src/grant/db.py INSERT INTO permissions (user_id, permission) VALUES (?, ?) user permissions storage account_class 1. get_subject resolves subject from request h… 2. check verifies if subject can perform op on… 3. resolve maps account_class to feature bundle 4. entitlements_for returns feature keys for a… JWT Token Payload {"sub": "user:123", "email": "user@example.com", "tier": "pro"} Account Class JSON {"tier": "pro", "skin": "pro-skin", "plugins": ["plugin1", "plugin2"]} The source does not show any direct interaction with an external process or third party in this subsystem. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Holon Fabric — Mailbox & Dispatch (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | YAML holon → outbox → worker → skill-matched sub-agent → archive. 1 - Holon Emission emit() holon/emitter.py:120 decisions dict analyst_signals dict ~/.kevin/mailbox/out/ curapedis-signal-*.md trading-signal… 2 - Agent Tracking acquire_lock() tools/multi-agent-framework/agent_tracking.py:180 agent_name task_description .locks/ planner.lock executor.lock reviewer.lock lock file 1. Emit trading-signal holon to mailbox 2. Acquire lock for agent Holon content example --- type: trading-signal from: curapedia date: 2023-10-05 ticket: KAN-338 model_tier: standard required_skills: [] --- # Portfolio Manager Decision — AAPL, GOOGL ## Orders - BUY AAPL 100 shares (confidence: 95%) - SELL GOOGL 50 shares (confidence: 80%) ## Analyst Consensus SignalAgent(AAPL): Bullish (90%) SignalAgent(GOOGL): Bearish (75%) ## kevin_value cost: $100 | saved: $200 | provider: premium Lock file content example Planner 2023-10-05T14:23:12Z session-20231005-1423 Planning phase The source does not show any direct interaction between the holon emission and agent tracking processes. They operate independently. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
VersionVerifier + AutoHealer (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Version mismatch alert → cooldown gate → systemctl restart → re-identify. 1 - Version Mismatch Alert kv/version/mismatch-alert VersionVerifier.py:120 2 - Cooldown Gate AutoHealer._on_mismatch_alert auto_healer.py:150 3 - Systemctl Restart AutoHealer._restart_service auto_healer.py:240 systemctl restart kevin-{service} service name 1. VersionVerifier publishes mismatch alert 2. AutoHealer receives mismatch alert 3. AutoHealer checks cooldown 4. AutoHealer triggers systemctl restart Mismatch Alert Payload { "service": "daemon", "expected_version": "2026-05-23T074530Z-a3f8e2c", "actual_version": "2026-05-23T074501Z-b7f2a4d", "action_required": "restart", "timestamp": 1715813520 } The source does not show any implementation for re-identifying the service after restart. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
MQTT Topic Topology (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | All canonical topics with producers/consumers in one map. EventBus Initialization EventBus.__init__ _subscribers _filters _last_consume _overflow_counts event_bus_lvc.db CREATE TABLE IF NOT EXISTS lvc SELECT event FROM lvc ORDER BY ts ASC initializes in… Event Publishing EventBus.publish bus.publish() kv/events/{event_type} _lvc_queue.put_nowait(event) event_bus_lvc.db INSERT OR REPLACE INTO lvc (event_type, ts, event) VALUES (?, ?, ?) batch.append(ev2) publishes even… Event Subscription EventBus.subscribe subscribe() asyncio.Queue(maxsize=_SUBSCRIBER_MAX_DEPTH) SSE client GET /api/events GET /api/events?filter=holon:*,job:* registers subs… 1. Initialize EventBus 2. Load LVC from database 3. Start LVC writer thread 4. Subscribe to events 5. Publish event to MQTT… 6. Update LVC in database 7. Deliver event to match… Service Identity Payload { "service": "daemon", "version": "2026-05-23T074530Z-a3f8e2c", "role": "owner", "status": "starting", "environment": "d… Version Heartbeat Payload { "service": "daemon", "version": "2026-05-23T074530Z-a3f8e2c", "role": "owner", "status": "healthy", "uptime_seconds":… The NATS integration is optional and depends on the configuration. The LVC writer thread ensures that the last value cache is persisted to disk. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Billing Pipeline — Stripe → Queue → ClickHouse (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Meter events → queue → holon worker → Stripe + ClickHouse + tax. 1 - Billing API Requests Client POST /api/billing/accounts GET /api/billing/accounts/{account_id} POST /api/billing/invoices GET /api/billing/invoices/{invoice_id} billing_router.py create_account() get_account() create_invoice() get_invoice() account details 2 - Billing Queue billing_queue.py enqueue() execute() BillingQueueEntry operation_id op_name params operation deta… 3 - Billing Processing billing_service.py create_account() get_account() create_invoice() finalize_invoice() mark_paid() Stripe stripe_charge_id ClickHouse holons table account data invoice data 1. Client sends request to billing A… 2. billing_router.py processes the r… 3. billing_queue.py enqueues the ope… 4. billing_service.py executes the o… 5. Stripe and ClickHouse are updated… Create Account Request {"name": "Company Inc", "email": "contact@company.com", "tier": "standard", "state": "CA"} Queue Depth Event {"max_concurrent": 3, "in_flight": 1, "available": 2, "queued": 5, "ts": 1672531200} The billing API is deprecated and should use MCP tools instead. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Ralph Loop — Autonomous Claude Loop (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | tick → claude_exec → tools → holon emit → audit (daemon-required). 1 - Reception - Listen for holon work items MQTT broker kv/holon/dispatch/<target> subscribe_to_topics() daemon/docs/RALPH_SPEC.md:300 holon queue E_QUEUE_FULL holon work item 2 - Validation & Grooming - Check holon format, dependencies, blast radius validate_holon() daemon/docs/RALPH_SPEC.md:400 check_dependencies() daemon/src/claude_exec.py:150 groom() daemon/src/claude_exec.py:200 holon validati… 3 - Execution & Reporting - Run the holon work, capture output _run_claude() daemon/src/claude_exec.py:400 execution log http://localhost:8001/api/ralph/logs/KAN-167 Claude CLI claude --print execution outp… 1. MQTT broker publish… 2. subscribe_to_topics… 3. holon is queued in… 4. validate_holon() ch… 5. check_dependencies(… 6. groom() enhances ho… 7. _run_claude() runs… 8. execution log captu… Dispatch Message {"holon_id": "KAN-167", "title": "Implement user authentication", "description": "Add JWT-based auth to daemon API endpoints", "type": "coding|refactor|test|docs", "target_service": "daemon", "priority": 1-5, "blast_radius": "low|medium|high|critical", "estimated_effort": "1h|2h|4h|8h|16h", "dependencies": ["KAN-166"], "required_skills": ["python", "fastapi", "jwt"], "constraints": { ... }, "acceptance_criteria": [ ... ], "context": { ... }, "role": "claude-architect", "timeout_seconds": 3600, "max_retries": 2, "callback_topic": "kv/holon/result/<holon_id>"} Status Message {"holon_id": "KAN-167", "status": "queued|validating|executing|completed|failed", "phase": "validation|execution", "progress_percent": 0-100, "timestamp": "2026-05-23T18:15:00Z", "worker_id": "ralph-1", "service_version": "2026-05-23T074530Z-a3f8e2c", "message": "Validation passed, starting execution", "validation_errors": [], "execution_log_url": "http://localhost:8001/api/ralph/logs/KAN-167"} The source does not show any specific handling for blast radius approval or resource availability checks, so these are implied based on the specification. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
OTA Firmware Flow (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Device registry → flash → self-test → commit or rollback. 1 - DEVICE REGISTRY - Maintains device records DeviceRegistry add_device() lookup_by_mac() upsert_by_mac() 2 - FIRMWARE DOCTOR - Monitors and corrects firmware health FirmwareDoctor on_device_online() on_device_offline() on_ota_flashed() _watch_ota_reboot() report_telemetry() 3 - OTA MANAGER - Handles firmware updates OTAManager beginUpdate() lastError() OTARollback begin() _loadNvs() 1. DeviceRegistry adds or updates de… 2. FirmwareDoctor monitors device st… 3. FirmwareDoctor triggers OTA updat… 4. OTAManager begins firmware update… 5. OTARollback checks for rollback c… DeviceRegistry.add_device() payload {"device_id": "KV-1234", "name": "Blaine", "friendly_name": "Blaine", "hardware_class": "V3", "mac_address": "AA:BB:CC:D… OTAManager.beginUpdate() payload {"url": "https://example.com/firmware.bin"} FirmwareDoctor uses event_bus for communication with other components. OTARollback is not fully detailed in the source, so some steps are inferred. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Daemon HA + Peer Federation (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-02 | HA election + peer auth + cross-machine state. 1 - Daemon HA Election DaemonHA.elect() daemon_ha.py:421 GET /api/health primary election daemon/primary/heartbeat daemon_ha.py MQTT topic heartbeat message DaemonHA._listen_for_primary() daemon_ha.py MQTT subscription detect primary StandbyMirror daemon_ha.py:203 in-memory mirror state sync election result 2 - Daemon Federation publish_holon_sync() daemon_federation.py:164 POST /api/daemon/federation/holon holon sync kv/net/services/{machine_id}/{svc} fabric_peer.py:123 MQTT topic service announcement announce_service() fabric_peer.py:87 MQTT publish register service holon state ch… 3 - Daemon Presence _build_payload() daemon_presence.py:102 UDP broadcast payload presence data UDP port 8765 daemon_presence.py:93 UDP broadcast machine discovery ops DB (machines table) daemon_presence.py:120 database table register machine presence annou… 1. DaemonHA starts election 2. Listen for primary heartbeat 3. If no heartbeat, promote to… 4. Publish primary heartbeat l… 5. Announce presence via UDP b… 6. Register services on MQTT Heartbeat Payload { "machine": "ORION-PC", "pid": 12345, "uptime_s": 60.0, "role": "primary", "api_url": "http://orion.local:8001" } Holon Sync Payload { "holon_id": "xxx-123-abc", "action": "claimed", "role": "flynn-claude", "timestamp": "2026-05-20T12:34:56Z" } DaemonHA election and state sync are handled by DaemonHA class. Daemon Federation uses MQTT for service announcements and HTTP for state replication. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
EventBus Internals (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Deep dive: subscriber queues, slow-consumer drop, MQTT bridge. 1 - EventBus Initialization EventBus.__init__ daemon/src/event_bus.py:631 SUBSCRIBER_MAX_DEPTH _load_lvc event_bus_lvc.db kv/events/{event_type} CREATE TABLE IF NOT EXISTS lvc subscriber que… 2 - Event Publishing EventBus.publish daemon/src/event_bus.py:publish kv/events/{event_type} _SUBSCRIBER_EVICT_OVERFLOWS MQTT client client.publish(topic, message) NATS module nats_bus.publish_event(event_type, event) event data MQTT topic 3 - Event Subscription EventBus.subscribe daemon/src/event_bus.py:subscribe asyncio.Queue(maxsize=_SUBSCRIBER_MAX_DEPTH) SSE subscriber GET /api/events filtered events subscriber reg… 1. Initialize EventBus with max depth and LVC… 2. Publish event to subscribers, MQTT, and NATS 3. Subscribe new SSE client with filters 4. Handle overflow by dropping old events EventBus publish payload { "e": "holon:queued", "ts": <unix_float>, "id": "<uuid8>", "holon_id": "...", "to": "flynn" } KVEvent JSON structure { "ts": "2026-05-12T16:30:00+00:00", "instance": "instance-a", "service": "daemon", "event_type": "startup", "severity":… EventBus handles both internal and external event publishing/subscribing. MQTT and NATS are optional transports, controlled by mount methods. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Config Sync + Hot Reload (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-02 | services.yaml ↔ env ↔ running services. 1 - CONFIG_SYNC_LOOP - Configuration Sync Loop ConfigSync.start() _sync_loop() Flynn daemon (master) GET /api/config/version local config version config_server.get_config_version() _sync_once() _fetch_master_version() sync event master config… local config v… 2 - CONFIG_HOT_RELOAD - Hot Reload SIGHUP signal do_reload() snapshot_env() _categorise() _apply_live_safe() env vars os.environ reload signal current env sn… 3 - CONFIG_BUS - Reactive Config Bus ConfigBus.set() _set_nested() _publish() config.json daemon/config.json event_bus config:update config:queue_depth new config val… persisted to d… 1. Start Config… 2. Fetch master… 3. Compare with… 4. Detect drift… 5. Apply change… 6. Log sync eve… 7. Handle SIGHU… 8. Snapshot cur… 9. Categorize c… 10. Apply live-… 11. Publish con… SyncEvent payload { "timestamp": "2023-10-01T12:00:00Z", "status": "success", "local_hash": "abc123...", "master_hash": "def456...", "error": null, "changes_applied": { ... } } do_reload() result { "changed_keys": ["KEVIN_LOG_LEVEL", "GRANT_ACCESS_TTL_S"], "restart_required_keys": ["KEVIN_DATABASE_URL"] } MQTT subscription is optional and falls back to HTTP polling if unavailable. Hot reload only applies live-safe changes without restarting the daemon. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Email Automation (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Inbox → automate → send. 1 - INBOX PROCESSING EmailClassifier.classify() GET /api/ai/query _CLASSIFY_PROMPT vault/inbox/holons/<ts>_<subject>.md create_holon() email message 2 - HANDLER REGISTRY HandlerRegistry.handlers_for() register_category() register_tier() create_kanban_ticket() kanban_board classification 3 - EMAIL SENDING send_email() _load_template() _render() Postmark API POST /email Resend API POST /emails handler results 1. EmailClassifier.classify() proces… 2. HandlerRegistry.handlers_for() de… 3. create_holon() deposits holon in… 4. create_kanban_ticket() optionally… 5. send_email() prepares and sends t… Email Classification JSON Schema { "tier": <1|2|3|4>, "tier_name": <"skip"|"info_only"|"meeting_info"|"action_required">, "category": <"newsletter"|"digest"|"receipt"|"alert"|"calendar_invite"|"renewal"|"bill"|"inquiry"|"todo"|"reply_needed… "confidence": <0.0-1.0>, "summary": "<one sentence>", "suggested_reply": "<draft reply or empty string>", "extracted": {} } Email Template YAML Front-Matter --- subject: "Welcome to Kevin, {{name}}!" --- The system does not show integration with external email clients or third-party services beyond the defined APIs. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Fleet Control (Groups + Devices) (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Group routing, command fanout. 1 - Fleet Control Router - Handles library and execution requests _index_holons() daemon/src/fleet_control_router.py:204 _load_holon_content() daemon/src/fleet_control_router.py:238 _execute_holon() daemon/src/fleet_control_router.py:265 holon index holon content 2 - Fleet Groups Router - Manages device groups and commands _dispatch_command() daemon/src/fleet_groups_router.py:40 DeviceRegistry daemon/src/device_registry.py command dispat… 3 - Capability Deployment - Handles capability distribution _validate_capability_artifact() _create_deployment_plan() _monitor_deployment() capability val… deployment plan 1. Marco queries /api/fleet-control/library 2. Daemon indexes holons and returns library i… 3. User selects a holon, Marco posts to /api/f… 4. Daemon loads holon content and executes it… Holon Index Response { "categories": { ... }, "total_count": 10, "last_indexed": "2023-10-01T12:00:00Z" } Deployment Plan Request { "capability_id": "skill-sync-v2.1", "target_scope": { ... }, "deployment_strategy": "staged" "batch_config": { ... } } The capability deployment steps are not fully implemented in the source code. Device registry and command dispatch rely on external components not shown. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Tick — Options Data Spec (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Field registry + spec for options data plane. 1 - TICK SESSION INIT - Initialize Tick session TickSession __init__ TickSession GrantIntegration check_field_access load_entitlements FieldRegistry get_field list_fields user credentia… entitlements 2 - DATA FETCHING - Fetch and process market data TickSession snapshot subscribe history MaxGateway fetch_snapshot subscribe fetch_history LVCStorage write_tick query_ticks symbol query live data stre… 3 - AI INTEGRATION - Run AI inference TickSession ai Annie (AI service) market data co… 1. Initialize Tick sessio… 2. Load user entitlements… 3. Fetch field definition… 4. Query snapshot for cur… 5. Subscribe to live upda… 6. Write historical ticks… 7. Run AI inference on li… Example Snapshot Response { "symbol": "AAPL", "timestamp": "2023-10-01T14:00:00Z", "fields": { "bid": 150.25, "ask": 150.75, "last": 150.50 }, "tier": "pro" } Example AI Request Context Recent market data for AAPL: 2023-10-01T13:59:00Z: bid=150.20, ask=150.70, last=150.45, volume=1000 2023-10-01T14:00:00Z: bid=150.25, ask=150.75, last=150.50, volume=1200 The AI integration is currently stubbed and returns an acknowledgment message instead of actual AI output. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Plugin Architecture (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Self-describing plugin manifests + lifecycle. 1 - Alertmanager Configuration alertmanager.yml global templates route receivers inhibit_rules 2 - Local Broker Bridge Config BRIDGE-CONFIG-LOCAL-BROKERS.md emqx.conf deploy order agents' tasks failure modes 3 - Docker Compose Strategy docker-compose.yml services networks volumes docker-compose.orion.yml overrides for Orion docker-compose.og2.yml overrides for OG2 docker-compose.vera.yml overrides for Vera 1. Configure Alertmanager with globa… 2. Define alert templates and routin… 3. Set up local broker bridges in em… 4. Deploy services using docker-comp… 5. Verify bridge connections and mes… Alertmanager Global Configuration global: resolve_timeout: 5m slack_api_url: '${SLACK_WEBHOOK_URL}' EMQX Bridge Configuration Snippet bridges.mqtt.to_vera { enable = true server = "ssl://bus.iiiai.us:8883" username = "<MACHINE>-cld" password = "<from .env.vera BUS_<MACHINE>_PASSWORD>" clientid = "<MACHINE>-bridge" } Alertmanager configuration is self-contained in alertmanager.yml. Local broker bridge configurations are documented in BRIDGE-CONFIG-LOCAL-BROKERS.md. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
OpenSpec Spec-Driven Development (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | openspec/config.yaml -- propose / review / implement / archive pipeline Developer Claude / AG / Orion /opsx:propose openspec propose "desc" reads openspec/config.yaml KAN ticket reserved first openspec/changes/ proposal.md + design.md tasks.md (per feature) openspec/config.yaml project context + rules proposal / tasks / design Review Phase read proposal.md openspec validate adjust before coding /opsx:apply reads tasks.md checklist Claude implements tasks max 2h chunks each Agent Execution Claude (architecture) AG (firmware/flash) Ollama (boilerplate) Codebase feature branch conventional commits /opsx:archive merges changes/ deltas into openspec/specs/ cleans changes/ dir openspec/specs/ persistent spec truth merged per feature honest count: 0 of 29 changes/ ever archived here (2026-08-01) Holon Deposit docs/holons/ required_skills frontmatter for major features openspec view interactive TUI all specs + changes Backlog KAN Ticket backlog/.next-kan reserve BEFORE propose 1 /opsx:propose "feature" 2 generate artifacts reads rules proposal.md ready 3 openspec validate 4 execute tasks 5 write code openspec view 6 /opsx:archive 7 merge to specs/ deposit holon if major reserve KAN before propose Sequence 1 Reserve KAN ticket from backlog/.next-kan BEFORE proposing. Put ticket number in proposal. 2 Run /opsx:propose "feature description". OpenSpec reads config.yaml context + rules to generate proposal.md, design.md, tasks.md. 3 Review artifacts. Run openspec validate (exits non-zero to block implementation if spec is incomplete). 4-5 Run /opsx:apply. Claude reads tasks.md checklist; each task max 2h; firmware tasks include bump-flash-confirm cycle. 6 Execution routes to correct agent: Claude for architecture/daemon, AG for firmware/flash, Ollama for boilerplate. 7 /opsx:archive merges spec deltas into openspec/specs/ (persistent truth) and cleans openspec/changes/ workspace. openspec/config.yaml (rules excerpt) proposal: - Under 400 words - Include Non-goals section - Reference KAN ticket number tasks.md chunk (agent-config-template-library) - [x] 2.1 Add `templates` root to _build_roots() in agent_config_api.py - [x] 6.6 .kvg cache regenerates after deletion, no data loss (8/8 tests pass) Holon frontmatter (docs/holons/outbox/, real example) holon_id: 1784513686.22664-render-openspec-workflow character: diagram-bot action_type: render-diagram required_skills: [svg-dataflow, kevin-design-system]
Backlog Ticket Pipeline (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | backlog/ KAN tickets + kanban_api.py approval gate + backlog_api.py dispatch + holon mailbox 1 · RESERVE — claim a number before writing anything Agent session Orion / Flynn / OG2 TICKET_PROTOCOL.md _reserve_kan() kanban_api.py:731 with _kan_lock: n, n+1 backlog/.next-kan one integer, git-tracked kanban_api.py:75 claim read+write DEFECT — this counter cannot allocate unique numbers _kan_lock is per-PROCESS; .next-kan is git-tracked, so it FORKS with every branch. Two sessions both read 1098, both "reserve" it, both are correct on their own branch. Observed 2026-08-01 (KAN-1098/1099 collision). Fix: KAN-1106 timestamp uid = identity. 2 · WRITE + SERVE — markdown in git is the store backlog/ KAN-{n}-{slug}.md YAML frontmatter + body BOARD.md, GROOMED/ git-tracked, PR-reviewable backlog_router.py GET /api/backlog :377 GET /api/backlog/{t} :406 PATCH /api/backlog/{t} :430 POST /{t}/milestone :521 kanban_api.py GET /tickets :1166 GET /board :1225 GET /triage :1217 POST /groom :1293 backlog_offsite_router.py GET /offsite :93 GET /ticket/{kan_id} :110 POST /offsite/synthesize:138 GET /offsite/health :437 Marco (Mona SPA) KanbanPage.tsx — board, drawer, filters offsite panel — thrusts + groomed Read-only surfaces; every mutation goes back through the routers on the left. write KAN-N.md 3 · APPROVAL GATE → DISPATCH — no kanban-originated work runs unapproved approval gate POST /tickets/{id}/approve :1401 POST /tickets/{id}/unapprove :1432 kanban_pipeline.py config/kanban-pipeline.yaml dispatch POST /tickets/{id}/dispatch :1460 POST /api/backlog/dispatch/batch backlog_api.py:91 auto_approve default false holon mailbox holon_mailbox.py BEGIN EXCLUSIVE claim TTL recovers orphans KEVIN_HOME/db holon worker tools/holon_worker/ worker_loop.py claim → execute → commit Walt cost ledger X-Kevin-Ticket: KAN-N fabric_proxy/telemetry.py Real spend joined back to the ticket. drop_holon blocked_unapproved → back to board 1. reserve KAN-N 2. write KAN-N.md 3. serve to Marco 4. approve 5. dispatch 6. worker claims 7. cost attributed Ticket frontmatter — backlog/KAN-1106-immutable-ticket-uid.md --- key: KAN-1106 # LABEL, renumberable pre-merge only title: "Immutable ticket uid — identity is a timestamp" status: backlog # backlog | in_progress | done priority: "High" type: "Bug" owner: claude labels: [kanban, ticket-protocol, offline-safe, identity] related: [KAN-1107, KAN-1089] required_skills: - kevin-daemon-framework # routes the holon to a capable worker modules_affected: [daemon/src/kanban_api.py, backlog] created: "2026-08-01T09:10:00-0400" --- DispatchResult — POST /api/backlog/dispatch/batch { "ticket": "KAN-1106", "status": "blocked_unapproved", # or "dispatched" "holon": "", # id appears only once approved "reason": "ticket not approved for dispatch" } The gate is per-ticket and never silent An unapproved ticket comes back as blocked_unapproved rather than being dropped from the batch — a silently shrunk batch is indistinguishable from a batch that had less work in it. KAN-N is the correlation id ticket → holon → branch → PR → Walt spend. That is exactly why the number must stop carrying identity: renumbering would break every reference, so KAN-1106 moves identity to an immutable uid and freezes the label at merge. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
AI Dispatch Cascade (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Quality-aware provider cascade -- cheap first, Claude Haiku review, escalate + Annie RAG inject. 1 - AI Dispatch API - Handles incoming requests and dispatches to providers POST /api/ai/dispatch daemon/src/ai_dispatch_api.py:1437 dispatch_request _get_worker_token() _walt_timeout_for_tier() jobs.db user_prefs table _user_profile ollama → groq → claude http://localhost:11434 http://localhost:{KEVIN_PORT_DAEMON} user request dispatched job provider respo… 2 - Quality Review - Claude Haiku review and escalation quality_review _bus_publish() _role_has_authority() Claude API ANTHROPIC_API_KEY claude-haiku-4-5 FLO rules cache _FLO_RULES_CACHE provider respo… quality score 3 - RAG Context Injection - Annie service integration _inject_rag_context annie:rag_inject:request annie:rag_inject:response Annie Service http://localhost:{KEVIN_PORT_ANNIE} prompt with co… 1. Receive user request v… 2. Dispatch request to pr… 3. Perform quick quality… 4. Check quality score ag… 5. Escalate to next tier… 6. Inject RAG context usi… 7. Return best response w… User request payload {prompt: 'What is the meaning of life?', provider: 'ollama', context: {}, role: 'user', quality_threshold: 6} Provider response payload {provider: 'claude', score: 8, response: 'The meaning of life is subjective.', cost: 0.3, latency: 200} The system uses environment variables for configuration and external service URLs. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
AI Proxy + Savings Ledger (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Transparent OpenAI-compatible proxy to Sibyl/Carousel with SQLite cost ledger + SSE feed. Request Handling Client POST /proxy/v1/chat/completions GET /proxy/savings ai_proxy_router.py openai_proxy() _forward_to_sibyl() request payload Sibyl Interaction Sibyl Carousel http://localhost:{_daemon_port}/api/carousel/ask ai_proxy_router.py _forward_to_sibyl() translated req… Data Storage SQLite Ledger ai_proxy_savings.db ai_proxy_router.py _record() savings record 1. Client sends request to proxy 2. Proxy translates and forwards req… 3. Sibyl processes the request and r… 4. Proxy calculates savings and reco… 5. Proxy returns response to client Request Payload (OpenAI chat) { "messages": [{"role": "user", "content": "Hello!"}], "stream": false } Savings Record (SQLite) { "id": "123e4567-e89b-12d3-a456-426614174000", "ts": 1672531200.0, "target": "openai", "model": "gpt-3.5-turbo", "tokens_in": 100, "tokens_out": 200, "direct_usd": 0.75, "sibyl_usd": 0.60, "saved_usd": 0.15, "latency_ms": 123.45, "status": "ok" } The proxy does not handle SSE streaming directly; it forwards the stream to the client. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
MCP Server -- 70+ Tools (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | HTTP+SSE MCP server exposing bus, vault, RAG, dispatch, billing, and prod-ops tools to Claude. 1 - HTTP API Handling build_mcp_app GET /mcp/sse POST /mcp/messages/ Server _list_tools() bus_publish bus_get bus_walk SseServerTransport /mcp/messages/ HTTP request Tool list 2 - Bus Operations bus_publish event_bus.publish() UPDATE EXECUTE bus_get LVC record bus_walk bus.walk(pattern) glob pattern Publish message Get LVC record 3 - Storage Operations hank_get storage.get(key) vault key hank_set storage.set(key, value) JSON value hank_list storage.list(pattern) glob pattern Read vault key Write vault key 1. Client sends HTTP r… 2. Server processes th… 3. Client sends POST r… 4. Server lists availa… 5. Client invokes bus_… 6. bus_publish publish… 7. Client invokes bus_… 8. bus_get retrieves L… HTTP request to /mcp/sse GET /mcp/sse Content-Type: application/json bus_publish payload { "subject": "node.status.ABC123", "payload": {"status": "online"}, "op": "UPDATE" } The source does not show the implementation of runpod_execute, so it is omitted from the diagram. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Agent Control Framework (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Approval gates (HARD_GATE/SOFT_SIGNAL/INSPECTION) + checkpoint resume + phase state + visibility filtering. 1 - Approval Management ApprovalRequest approval.py:30 ApprovalStatus ApprovalType ApprovalStore approval.py:155 create() get_pending() Approval reque… 2 - Execution Checkpointing ExecutionCheckpoint checkpoint.py:30 CompletedStep progress_percentage() CheckpointStore checkpoint.py:122 save() get_latest() Checkpoint sav… 1. Create ApprovalRequ… 2. Save to ApprovalSto… 3. Retrieve pending ap… 4. Approve or deny req… 5. Update state based… 6. Create ExecutionChe… 7. Save to CheckpointS… 8. Resume from latest… ApprovalRequest JSON Example { "id": "apr-123", "agent_id": "renewal-prep-1", "action": "send_renewal_packet", "description": "Send renewal packet to customer", "approval_type": "hard_gate", "required_approvers": ["csm_lead"], "deadline": "2026-05-21T13:59:23Z", "status": "pending" } ExecutionCheckpoint JSON Example { "task_id": "task-1", "agent_id": "agent-1", "current_step": 5, "total_steps": 10, "completed_steps": [...], "current_context": { ... }, "agent_memory": { ... } } ApprovalRequest and ExecutionCheckpoint use Pydantic for schema validation. StateStore and CheckpointStore are in-memory by default, suitable for development. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Holon Queue Pipeline (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Pull-based atomic dispatch queue -- workers claim holons, module locking, Caveman compression, swarm heartbeats. 1 - QUEUE ROUTER - Handles API requests and queue operations queue_router.py GET /api/holons/ POST /api/holons/claim PUT /api/holons/reap HolonQueueStore holon_queue_store.py INDEX_DB_PATH PRODUCED_BASE API request 2 - CAVEMAN COMPRESSION - Compresses holon bodies caveman_holon_hook compress_holon_body initialize_caveman INBOX_DIR inbox_fs.py holon-queue-index.json holon body 3 - HOLON MAILBOX - Manages holon storage and claims HolonMailbox drop_holon claim_holon commit_result holon_mailbox.db _DDL holons table holon_claims table holon data 1. Receive API request 2. Process queue operation 3. Claim holon from mailbox 4. Compress holon body if enabled 5. Commit result to mailbox API Request Payload { "holon_id": "12345", "body": "work payload" } Compression Metadata { "savings_pct": 20.5, "cost_usd_saved": 0.1234 } The system uses SQLite for durable storage and MQTT for event emission. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Swarm Dispatch Manager (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Batch holon routing -- round-robin, load-aware, stage-aware strategies for up to 1000 holons. 1 - Dispatch Request Handling SwarmDispatchManager dispatch() GET /api/dispatch validate_batch_size len(request.holons) > 1000 validate_batch_exists request.batch_id in self.batches batch request 2 - Batch State Initialization BatchState self.batches[request.batch_id] = batch create_batch_state BatchState(batch_id=request.batch_id, ...) batch state 3 - Routing and Publishing _apply_dispatch_rule self._apply_dispatch_rule(rule=DispatchRule(request.dispatch_rule), ...) MQTTClient self.mqtt.publish(f'kv/batch/{request.batch_id}/started', {...}) _publish_batch_status await self._publish_batch_status(request.batch_id) routing manife… 1. SwarmDispatchManager receiv… 2. validate batch size and exi… 3. create batch state 4. apply dispatch rule 5. publish batch started event 6. publish initial status Batch Dispatch Request Payload { "batch_id": "unique_batch_id", "dispatch_rule": "round_robin", "holons": [...], "timeout_seconds": 300, "notify_on_completion": false } MQTT Publish Payload { "batch_id": "unique_batch_id", "holon_count": 10, "dispatch_rule": "round_robin", "routing_manifest": [...], "timestamp": 1633072800.0 } The source code does not show the implementation of _stage_aware_dispatch method, so it is omitted in the diagram. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Marco Agent Bridge (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | HTTP+SSE process controller -- start/stop/restart services via plugin.json manifests + Mx bus. 1 - HTTP+SSE Controller marco_agent_bridge.py GET /api/marco/vault/* POST /api/health MARCO_URL MARCO_AGENT_PORT _registry AgentRecord _prune_stale() last_heartbeat HTTP request 2 - Process Controller ProcessController dispatch() _start() _stop() _services ManagedService name cmd control message 3 - SSE Fan-out _broadcast() json.dumps(event) asyncio.Queue.put_nowait(data) _sse_queues asyncio.Queue event event data 1. Receive HTTP request 2. Process control message via dispa… 3. Start/stop/restart service using… 4. Broadcast event to SSE subscribers 5. Prune stale agents HTTP Request Example { "method": "POST", "url": "/api/marco/vault/thing" } SSE Event Example { "type": "heartbeat", "agent_id": "12345" } The source does not show any direct interaction with the Mx bus or Hank vault, only proxying through HTTP requests. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Fleet Intel Pipeline (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Marco fleet panel -- Vibe to DynaRAG to Carousel to Holon intent pipeline with job polling. 1 - Intent Pipeline - Processes user intent through Vibe, DynaRAG, Carousel to Holon User POST /api/fleet/intel/intent fleet_intel_router.py _post() _publish() Vibe Service POST /vibe/process DynaRAG Service POST /dynarag/analyze Carousel Service _jobs dictionary _jobs_lock _prune_jobs() intent request vibe id dynarag topic holon id 1. User posts intent requ… 2. fleet_intel_router.py… 3. Vibe Service processes… 4. DynaRAG Service analyz… 5. Carousel Service gener… 6. Holon ID is assigned t… 7. Job status is updated… Intent Request Payload { "text": "Analyze the current market trends", "context": "Financial analysis", "tags": ["market", "finance"] } Intent Response Payload { "ok": true, "job_id": "123e4567-e89b-12d3-a456-426614174000", "vibe_id": "vibe_123", "dynarag_topic": "topic_abc", "status": "queued" } The source does not show the full implementation of the intent processing pipeline, only the entry point and some helper functions. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Marco Desktop — Electron + MQTT (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Main process MQTT bridge · renderer widget grid · tray. 1 - Build Process - Building the Electron App npm install package.json npm run dist:win build.js dist/ marco-config.json multi_instance ai.routing email.accounts dependencies i… build artifacts 2 - Configuration Management - Email Setup .marco-email-config.json accounts.spw1 default Email IPC Handlers email:accounts:list email:threads email config l… 3 - Development Tools - Debugging and Testing npm run test jest --testPathPattern=tests/ _debug.js Kevin — Universal Debug Overlay test results 1. Install dependencies with n… 2. Run build script for Window… 3. Configure email settings in… 4. Use IPC handlers to manage… 5. Execute tests using npm run… 6. Integrate debug overlay for… Example marco-config.json { "multi_instance": false, "ai": { ... }, "email": { ... } } Example .marco-email-config.json { "accounts": { ... }, "default": "spw1" } The build process uses esbuild to bundle the React app. Email configuration is managed via IPC handlers for secure access. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Marco VibeContextStore (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | vibe/raw → store → Ollama refinement → SQLite + LRU. 1 - MQTT SUBSCRIPTIONS event_bus.subscribe(['vibe/raw']) daemon/src/vibe_context_store.py:204 event_bus.subscribe(['vibe/refined']) daemon/src/vibe_context_store.py:210 raw vibe event 2 - EVENT CONSUMPTION _consume_raw_events() daemon/src/vibe_context_store.py:174 _on_vibe_raw(event) daemon/src/vibe_context_store.py:230 _consume_refined_events() daemon/src/vibe_context_store.py:186 _on_vibe_refined(event) daemon/src/vibe_context_store.py:250 raw vibe event refined vibe e… 3 - STORAGE AND CACHE SQLite database daemon/src/vibe_context_store.py:102 store_vibe() daemon/src/vibe_context_store.py:304 add_interpretation() vibe data interpretation… 1. Start MQTT subscriptio… 2. Consume raw vibe events 3. Process raw vibe event 4. Store raw vibe in SQLi… 5. Consume refined vibe e… 6. Process refined vibe e… 7. Add interpretation to… Raw Vibe Event Payload {"id": "vibe123", "raw_text": "I love coding!", "author": "JohnDoe", "metadata": {"source": "web"}, "tags": ["coding"]} Refined Vibe Event Payload {"id": "vibe123", "interpretation": "The user expresses enjoyment of coding.", "confidence": 0.95, "model_used": "Ollama… The source does not show any direct interaction with the Ollama refinement service, only handling of refined events. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Rho — Character Interaction (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | interact → memory append → fabric LLM → response + holon outbox. 1 - API Interaction - Handling HTTP requests FastAPI server GET /api/character POST /interact PUT /character/trait PUT /character/state POST /holon/emit get_character_state apps/rho/api/routes.py:32 CharacterStateResponse GET /api/character interact apps/rho/api/routes.py:50 InteractionRequest POST /interact update_trait apps/rho/api/routes.py:76 TraitUpdateRequest PUT /character/trait update_state apps/rho/api/routes.py:102 StateUpdateRequest PUT /character/state Character state Interaction re… Trait update State update 2 - Character Processing - Managing character state and interactions RhoCharacter apps/rho/character/rho.py:34 interact update_trait update_state CharacterMemory apps/rho/character/rho.py:10 name traits interactions state Interaction da… 3 - Holon Emission - Creating and emitting holons emit_holon routes.py HolonEmitRequest POST /holon/emit emit_action_holon apps/rho/holon/emitter.py:36 generate_holon_id action_type Holon request 1. Client sends i… 2. FastAPI server… 3. RhoCharacter p… 4. CharacterMemor… 5. Client request… 6. FastAPI server… 7. RhoCharacter r… 8. Client emits a… 9. emit_action_ho… 10. Holon is emit… Interaction request payload { "text": "Hello, rho!", "context": { "source": "test" } } Holon emission request payload { "action_type": "analysis", "description": "Analyze user input", "data": { "input": "Hello, rho!" }, "required_skills": [ "natural_language_processing" ] } The system does not currently integrate with an external LLM for response generation. Holon emission is a placeholder and does not actually persist holons in this simplified model. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Sterling — Options Data Session (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Stripe → HMAC → session → bridge → MQTT/LVC → WS frames. 1 - API REQUEST HANDLING POST /api/sterling/analyze analysis.py:458 sterling.analysis.analyze_endpoint Resolve OpenRouter Key resolve_openrouter_key() daemon/src/plugins/sterling/analysis.py:102 Ensemble Pack YAML KEVIN_ENSEMBLES_ROOT ensemble_packs.py:362 API request OpenRouter API… 2 - ANALYSIS ENGINE Build Prompt _build_prompt() daemon/src/plugins/sterling/analysis.py:304 OpenRouter (LLM) OPENROUTER_API_KEY httpx.post() Parse Signals _parse_signals() daemon/src/plugins/sterling/analysis.py:354 Prompt with gr… LLM response t… 3 - RESPONSE GENERATION Aggregate Decision _aggregate_decision() daemon/src/plugins/sterling/analysis.py:402 Return API Response POST /api/sterling/analyze sterling.analysis.analyze_endpoint Aggregated dec… 1. Receive POST /api/s… 2. Resolve OpenRouter… 3. Load ensemble pack… 4. Build prompt with g… 5. Send prompt to Open… 6. Parse LLM response… 7. Aggregate parsed si… 8. Return aggregated d… API Request Payload { "item": "AAPL", "start_date": "2023-01-01", "end_date": "2023-12-31" } LLM Response JSON { "analyst_key_1": { "signal": "positive", "confidence": 85, "reasoning": "Positive trend identified." } } The system uses OpenRouter for language model processing. Grounding data is fetched based on the pack's configuration. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Flo — Service Discovery (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | advertise manifest → subscribe patterns → registry + events. 1 - Alert Routing - Routes alerts to appropriate topics AlertRouter alert_router.py:40 mx://noted/session/event mx://flo/alert/noted MQTT Topics mx://holon/mailbox/email/inbound mx://daemon/process/state mx://daemon/primary/failover_event alert payload 1. AlertRouter initializes 2. Subscribes to raw sources 3. Processes incoming alerts 4. Publishes processed alerts to appropriate t… Processed alert for noted session event {"source": "noted", "severity": "warn", "count": 1, "summary": "1 session(s): session_awaiting_note", "ts_iso": "2023-04… Processed alert for email inbound {"source": "email", "severity": "info", "count": 1, "summary": "1 email(s) in inbox", "ts_iso": "2023-04-01T12:00:00Z"} AlertRouter supports both sync and async modes based on construction parameters. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Sibyl — sibyl.iiiai.us Production (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Public RAG surface on Vera, retrieval against iiiai_knowledge. 1 - Daemon Initialization __main__.py:main() python -m apps.sibyl.daemon sibyl_daemon.py:main() Daemon starts 2 - File Processing _INBOX ~/Kevin/inbox _InboxHandler:on_created() _process_file() _enqueue() _ingester.safe_ingest() New file detec… File processed 3 - Kevin Proxy KevinProxy:dispatch() _encrypt_prompt() _compute_hmac() http://kevin_ip/api/ai/dispatch _RESULTS_DIR ~/Kevin/results Encrypted payl… Response recei… 1. Daemon starts 2. New file detected in i… 3. File processed and enq… 4. Payload encrypted and… 5. Encrypted payload sent… 6. Response received from… 7. Result written to disk Kevin API Payload {"job_id": "12345", "product": "example", "task_type": "document_summarise", "prompt": "ciphertext", "context": {}, "sou… Kevin Response {"job_id": "12345", "result": "summary text", "task_type": "document_summarise", "provider": "kevin", "total_cost": 0.01… The source does not show a direct connection to the event bus or any external observability system. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Sibyl Client Daemon (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Local light daemon -- inbox file watcher, Ingester extraction, KevinProxy dispatch, ResultWriter, billing journal. 1 - Daemon Initialization __main__.py:main() python -m apps.sibyl.daemon sibyl_daemon.py:_load_grant_token() SIBYL_GRANT_TOKEN keyring.get_password('sibyl', 'grant_token') grant token 2 - File Watching and Ingestion _INBOX /home/user/Kevin/inbox sibyl_daemon.py:_InboxHandler.on_created() _start_watcher() _process_file() new file 3 - Kevin Proxy and Result Writing kevin_proxy.py:dispatch() _encrypt_prompt() _compute_hmac() httpx.AsyncClient.post() _RESULTS_DIR /home/user/Kevin/results result_writer.py:write_from_kevin_response() ResultWriter.write() json.loads() HolonEnvelope Kevin response 1. Daemon starts and l… 2. File watcher initia… 3. New file detected i… 4. File is moved to pr… 5. File is ingested in… 6. HolonEnvelope is di… 7. Kevin response is r… 8. Result is written t… Kevin API Dispatch Payload { "job_id": "123e4567-e89b-12d3-a456-426614174000", "product": "sibyl", "task_type": "document_summarise", "prompt": "ciphertext_here", "context": {}, "source_filename": "example.txt", "source_format": "text/plain", "nonce": "456e4567-e89b-12d3-a456-426614174000", "expires_at": "2023-10-01T12:00:00Z" } ResultWriter Write Payload { "job_id": "123e4567-e89b-12d3-a456-426614174000", "result_text": "Summary of the document.", "task_type": "document_summarise", "output_format": "md" } The system relies on Tailscale for network communication with Kevin. File processing is handled asynchronously to ensure non-blocking behavior. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Sibyl Platform -- Bootstrap, Session, Billing (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Server-side sibyl -- bootstrap Tailscale auth, session manager tiers, billing ClickHouse, inference handler. 1 - BOOTSTRAP Client POST /api/sibyl/bootstrap sibyl_bootstrap.bootstrap _provision_tailscale_key _sign_response bootstrap requ… 2 - SESSION MANAGEMENT Client GET /api/sibyl/stats sibyl_session_manager.get_manager create list_active session stats… 3 - INFERENCE PROCESSING Client POST /api/sibyl/process sibyl_router.process _require_tailscale _hmac_receipt inference requ… 1. Client sends bootstrap requ… 2. Server provisions Tailscale… 3. Client requests session sta… 4. Server lists active sessions 5. Client sends inference requ… 6. Server processes inference… Bootstrap Response Payload {tailscale_auth_key: 'ts-auth-key', fleet_key_b64: 'fleet-key-b64', kevin_tailscale_ip: '100.64.0.1', expires_at: '2023-10-01T12:00:00Z', signature: 'hmac-signature'} Inference Request Payload {job_id: 'uuid4()', client_id: 'client-id', product: 'sibyl', task_type: 'document_process', client_tier: 'standard', prompt: 'text to process', system: '', change_id: '', max_tokens: 2048, hard_cap_usd: 0.10} The source does not show any direct interaction with ClickHouse for billing in the provided code snippets. Session management and inference processing are handled by different modules. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Minnie -- Installer and Entry Point (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | PyInstaller exe -- _entry.py dispatcher, installer.py setup wizard, Windows schtasks ONLOGON registration. 1 - INSTALLER WIZARD - Handles user interaction and setup User --token arg SIBYL_GRANT_TOKEN env var installer.py:main() _store_token() _check_tailnet() _register_task() _start_task() grant token 2 - KEYRING - Stores sensitive information installer.py:_store_token() keyring.set_password() 3 - SCHEDULED TASK - Registers and runs the proxy service installer.py:_register_task() schtasks /Create installer.py:_start_task() schtasks /Run scheduled task… 1. User provides grant token 2. Installer stores token in OS keyr… 3. Installer verifies tailnet connec… 4. Installer registers scheduled tas… 5. Installer starts the registered t… Scheduled Task Command "C:\path\to\minnie.exe" --serve Keyring Storage keyring.set_password("sibyl", "grant_token", token) The source does not show any interaction with an external bus or MQTT topics. The installer handles both running from the PyInstaller exe and from source. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Minnie waltd -- AI Proxy Service (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | FastAPI waltd proxy -- Anthropic API shim to Kevin via Tailscale + HolonEnvelope + cost stats tray. 1 - REQUEST HANDLING FastAPI app GET /health POST /v1/messages POST /api/ai/dispatch _anthropic_to_envelope _extract_prompt(body) HolonEnvelope creation KevinProxy dispatch(envelope) request envelope 2 - STATUS POLLING _fetch_status GET /status FastAPI app GET /status status request 3 - TRAY ICON _build_menu_items _fetch_status() menu item creation pystray Icon update_menu(icon) setup(icon) status data 1. FastAPI app receives request 2. _anthropic_to_envelope crea… 3. KevinProxy dispatches envel… 4. Kevin responds with result 5. _kevin_to_anthropic convert… 6. FastAPI app returns respons… HolonEnvelope creation payload { "job_id": "uuid4()", "product": "minnie", "task_type": "ai_query", "prompt": "_extract_prompt(body)", "context": "{...}", "source_filename": "job_id.json", "source_format": "anthropic_messages" } Kevin response payload { "output": "response text", "usage": { "input_tokens": 100, "output_tokens": 200 }, "cost_usd": 0.05, "saved_usd": 0.03, "provider": "openai" } KevinProxy dispatches requests over Tailscale with encryption and HMAC signing. Tray icon polls status every 30 seconds and updates menu items. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Trixie — Knowledge / Content System (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | authoring → review → publish → multi-channel distribution. 1 - Corpus Loading load_corpus trixie/corpus.py:20 *.concept.json corpus_dir.rglob concepts Concept.model_validate holons table concepts list concept objects 2 - Rule Evaluation evaluate trixie/evaluator.py:15 text.lower() counter_examples violations Violation matched substrings severity order violation obje… 1. Load corpus from directory 2. Parse and validate concept files 3. Evaluate text against loaded concepts 4. Identify violations based on counter_exampl… Concept JSON Example { "id": "hipaa.164.508.authorization", "domain": "hipaa", "rule_text": "...", "severity": "critical", "tags": [], "examples": ["..."] } Violation Example { "concept_id": "hipaa.164.508.authorization", "domain": "hipaa", "severity": "critical", "matched": "...", "rule_text": "..." } The actual rule evaluation logic is not fully implemented in the provided source. The system currently uses a keyword scan for counter_examples, which is a P0 stub. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
DynaRag — RAG System (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | WP → Cloudflare → router :8403 → ChromaDB → Groq/Ollama → answer. 1 - MQTT SUBSCRIPTION - Subscribes to DynaRAG metric topics DynaRAGAnalyzer daemon/src/dynarag_analyzer.py:314 _on_metric_update() dynarag/{topic}/metrics 2 - ANALYSIS PROCESS - Analyzes metrics using Claude DynaRAGAnalyzer daemon/src/dynarag_analyzer.py:314 _analyze_metrics() dynarag/{topic}/analysis Carousel API http://localhost:{_daemon_port}/api/carousel/evaluate/ai POST /api/carousel/evaluate/ai metric data 3 - PUBLISHING RESULTS - Publishes analysis results DynaRAGAnalyzer daemon/src/dynarag_analyzer.py:314 _analyze_metrics() dynarag/{topic}/analysis MQTT Broker mqtt_client.py publish() analysis result 1. DynaRAGAnalyzer sub… 2. Receives metric dat… 3. Checks cooldown and… 4. Sends analysis requ… 5. Carousel selects mo… 6. Selected model proc… 7. Model returns analy… 8. DynaRAGAnalyzer cac… Analysis Request Payload {"topic": "dynarag/memory/metrics", "metric_type": "memory", "values": [1024, 2048], "timestamps": ["2023-10-01T12:00:00… Analysis Result Payload {"topic": "dynarag/memory/metrics", "timestamp": "2023-10-01T12:10:00Z", "analysis": "Memory usage is increasing steadil… The source code does not show any direct interaction with external services like Groq/Ollama or ChromaDB in this subsystem. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Ingestion + Knowledge Infrastructure (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | corpora → chunker → embedder → ChromaDB → metaindex. Ingestion - File Processing Ingester ingestion/ingester.py:272 ingest() safe_ingest() Knowledge - Embedding and Storage HolonEnvelope ingestion/holon_envelope.py:32 clear_buffer() job_id ChromaDB knowledge-infra/config.json:persist_dir data/chromadb collection_name HolonEnvelope 1. Ingester processes file 2. Extracts text and metadata 3. Infers task type 4. Creates HolonEnvelope 5. Stores in ChromaDB HolonEnvelope JSON {"job_id": "123e4567-e89b-12d3-a456-426614174000", "product": "sibyl", "task_type": "document_summarise", "prompt": "Extracted text from file.", "context": "Headers and hints.", "source_filename": "example.docx", "source_format": "docx", "output_format": ""} The source does not show the complete implementation of paper discovery, PDF conversion, or session briefing generation. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Kevin Clients — fleet-mobile + kevin-desktop (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Two surfaces, shared SDK, JWT auth, MQTT live state. 1 - App Initialization App.tsx:20 initializeStorage() React.useEffect() NavigationContainer RootNavigator SafeAreaProvider storage initia… 2 - Device List Navigation DevicesStackNavigator DevicesList DeviceDetail deviceStore.ts devices selectedDevice device list 3 - Device Detail Navigation DeviceDetailScreen DeviceInfoCard RelayControlCard CommandCard api.ts GET /api/devices/{id} POST /api/devices/{id}/relays/{num} device details 1. App initializes sto… 2. NavigationContainer… 3. DevicesStackNavigat… 4. User selects a devi… 5. DeviceDetailScreen… 6. DeviceInfoCard fetc… 7. RelayControlCard al… 8. CommandCard sends d… GET /api/devices/{id} response { "id": "device123", "name": "Device A", "online": true, "battery_pct": 85, "rssi": -60, "uptime_ms": 3600000, "version": "1.0.0", "hw": "ESP32" } POST /api/devices/{id}/relays/{num} request { "relayNum": 1, "state": "ON" } The source does not show MQTT integration or live state updates. Offline support and JWT authentication are mentioned but not detailed in the provided code. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Firmware Mx Architecture (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | ESP32-S3 V3/V4, FreeRTOS, NVS, OTA rollback. 1 - Initialization Adafruit_I2CDevice::begin() Adafruit_I2CDevice.cpp:50 Wire.begin() _begun flag Adafruit_I2CDevice.h I2C bus initia… 2 - Register Access Adafruit_BusIO_Register::write() Adafruit_BusIO_Register.cpp:170 _i2cdevice->write() Register data _buffer[4] _cached Data written t… 3 - Generic Device Communication Adafruit_GenericDevice::writeRegister() Adafruit_GenericDevice.cpp _writereg_func() Generic device busio_genericdevice_writereg_t Data written t… 1. Initialize I2C bus 2. Write data to register 3. Communicate with generic device I2C initialization payload Wire.begin(); _begun = true; Register write payload _i2cdevice->write(buffer, len, true, addrbuffer, _addrwidth); _cached = value; The source does not show the full implementation of address detection in Adafruit_I2CDevice::begin(). Generic device communication relies on function pointers for read/write operations. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Vera — Linode Prod Node (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Public surfaces hosted on Vera. 1 - API Endpoints server.py:app.post("/api/iiiai-status") POST /api/iiiai-status /var/www/iiiai/status.json _broadcast_update() server.py:app.post("/api/iiiai-sayings") POST /api/iiiai-sayings /var/www/iiiai/sayings.json append-only discipline server.py:app.get("/api/iiiai-status/stream") GET /api/iiiai-status/stream _sse_clients StreamingResponse status update sayings update 2 - File Operations /var/www/iiiai/status.json writes status reads status /var/www/iiiai/sayings.json writes sayings reads sayings status data 3 - External Services Resend.com API POST /emails _RESEND_API_KEY Groq API POST /openai/v1/chat/completions GROQ_API_KEY email payload 1. Receive POST /ap… 2. Validate token 3. Read status.json 4. Update fields if… 5. Write updated st… 6. Broadcast update… 7. Receive POST /ap… 8. Validate token 9. Overwrite saying… POST /api/iiiai-status request body { "left": "new left value", "right": "new right value" } POST /api/iiiai-sayings request body { "sayings": ["saying1", "saying2"], "rotation_seconds": 45 } The system uses environment variables for configuration, such as IIIAI_TOKEN and RESEND_API_KEY. The SSE broadcast mechanism is used to push updates to clients in real-time. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Docker Infrastructure (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-01 | Compose stack for MQTT/ClickHouse/EMQX. 1 - Infrastructure Layer kevin-postgres postgres_data:/var/lib/postgresql/data POSTGRES_USER: ${POSTGRES_USER:-kv} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme} emqx/emqx:5-latest mqtt_data:/opt/emqx/data EMQX_DEFAULT_USER: ${MQTT_USERNAME:-kevin-client} GET /api/health database conne… 2 - Kevin Services Layer daemon/Dockerfile KEVIN_PORT_DAEMON: ${KEVIN_PORT_DAEMON:-8001} GET /api/health python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:${KEVIN_PORT_DAEMON:-800… caddy:2-alpine ./Caddyfile:/etc/caddy/Caddyfile:ro DAEMON_URL: http://daemon:${KEVIN_PORT_DAEMON:-8001} daemon health 1. Copy .env.example → .env 2. Edit .env with settings 3. docker compose pull && docker com… 4. Verify daemon health: curl http:/… 5. Access Marco API: curl http://loc… Sample .env file POSTGRES_USER=kv POSTGRES_PASSWORD=changeme MQTT_USERNAME=kevin-client MQTT_PASSWORD=changeme Caddyfile snippet :80 { reverse_proxy kevin-daemon:8001 } InfluxDB and EMQX are not included in the current setup. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
nginx Public Edge (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-02 | TLS termination + routing for sibyl/spw1/iiiai surfaces. 1 - TLS Termination nginx/kevin.conf listen 80 listen 443 ssl ssl_certificate ssl_certificate_key 2 - Routing nginx/kevin.conf location / proxy_pass http://127.0.0.1:8001 location /mqtt proxy_pass http://127.0.0.1:8083 1. Nginx receives HTTP request on po… 2. Redirects to HTTPS 3. Nginx receives HTTPS request on p… 4. Routes request to FastAPI on port… 5. Routes WebSocket requests to EMQX… HTTP Request Payload { "method": "GET", "url": "/api/data", "headers": { "Host": "kevin.iiiai.us" "X-Real-IP": "192.168.1.100" "X-Forwarded-For": "192.168.1.100" "X-Forwarded-Proto": "https" } } WebSocket Upgrade Request { "method": "GET", "url": "/mqtt", "headers": { "Upgrade": "websocket", "Connection": "upgrade", "Host": "kevin.iiiai.us" } } The configuration does not show any specific handling for static files or other paths, so those are assumed to be handled by FastAPI. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Ansible Fleet Provisioning (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-02 | Per-machine bring-up: tailscale, services, env. 1 - DEPENDENCY INSTALLATION ansible-galaxy galaxy requirements.yml collections DEPLOYMENT ansible-playbook playbooks/kevin-full-stack.yml inventory.ini infrastructure VERIFICATION molecule test molecule.yml side-effect.yml verify.yml validation 1. Install dependencies with ansible… 2. Run main deployment playbook 3. Execute molecule test suite 4. Validate deployment with side-eff… 5. Final verification of services docker-compose.yml.j2 template version: '3.8' services: emqx: image: emqx/emqx:latest ports: - "1883:1883" - "8083:8083" - "8084:8084" - "8883:8883" - "18083:18083" nginx-kevin-api.conf.j2 template server { listen 80; server_name api.kevin.local; location /api/ { proxy_pass http://127.0.0.1:8000/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } The deployment playbook is highly idempotent, ensuring safe re-runs. Molecule tests cover various stages of deployment and validation. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
Sibyl Site + Oracle API (v2026-08-02T101544Z-ab2bbdebf5) 2026-08-02 | FastAPI oracle site -- SQLite visits/downloads/queries, Carousel AI routing, public query endpoint. 1 - API ENDPOINTS - handles HTTP requests index() GET / apps/sibyl-site/server.py:40 visit() POST /api/visit apps/sibyl-site/server.py:51 download() POST /api/download apps/sibyl-site/server.py:70 query() POST /api/query apps/sibyl-site/server.py:92 visit data download data query request 2 - DATABASE OPERATIONS - interacts with SQLite visits.db CREATE TABLE visits CREATE TABLE downloads _db() sqlite3.connect apps/sibyl-site/server.py:27 visit record 3 - CAROUSEL AI ROUTING - handles AI queries _carousel_ask() carousel.call.ask apps/sibyl-site/server.py:120 query() _connection_meta apps/sibyl-site/server.py:92 AI query reque… 1. Client sends a POST /api/vi… 2. visit() processes the reque… 3. Client sends a POST /api/do… 4. download() processes the re… 5. Client sends a POST /api/qu… 6. query() processes the reque… Visit Request Payload { "ip": "192.168.1.1", "forwarded": "10.0.0.1", "user_agent": "Mozilla/5.0"} } Query Request Payload { "query": "What is the meaning of life?", "model_tier": "standard" } Carousel AI routing is optional and depends on _CAROUSEL_AVAILABLE. The daemon and KevinProxy components are not directly involved in this dataflow. Legend actor = initiates work · process = code path · store = state on disk · bus = durable queue · dashed = separate process cyan = request flow · pink = state read/write · dashed green = pull / return path · red = refusal
← → navigate · Home/End · / search