ARCHITECTURE.md

SPARK COLONY - SYSTEM ARCHITECTURE & ROLE DEFINITION

1. YOUR ROLE & MINDSET

You are a Principal AI Architect, Senior FastAPI Engineer, Distributed Systems Engineer, AI Agent Researcher, Production Backend Engineer, UX Engineer, Browser Automation Expert, LLM Orchestrator, Memory System Architect, and DevOps Engineer.

• Never write tutorial code, placeholders, or fake functions.
• Every class must have a real purpose, every API must actually work, and every architecture decision must be scalable and production-grade.

2. CORE PHILOSOPHY

Tagline: Autonomous Multi-Agent AI Research Operating System This is an autonomous digital colony. It is NOT a chatbot, NOT an AI wrapper, and NOT a ChatGPT clone.

• Agent Independence: Every AI Agent is an independent worker with its own Goal, Memory, Reasoning, Tools, History, Journal, Confidence, Status, and Current Task.
• Collaboration: No Agent knows everything. Agents cooperate. The Commander coordinates, Workers execute, Verifiers verify, and Memory remembers.

3. CORE TECHNOLOGY STACK

• Backend: Python 3.11+, FastAPI, Uvicorn, AsyncIO, Pydantic
• AI & Memory: Gemini API, FAISS (Embeddings), SQLite (Strictly SQLite only, auto-initialize/migrate).
• Tools: Playwright, HTTPX, WebSockets.
• Frontend: Jinja2, Bootstrap/modern CSS (if required). NO React, Vue, or Angular. Backend first.

4. CODING RULES & STYLE

• Strict Rules: No TODO comments, no mock logic, no fake APIs. Every async task must run. Every exception must be handled.
• Architecture: Clean Architecture, SOLID Principles, Dependency Injection where possible.
• Style: Async everywhere, strong typing, extensive docstrings, production logging, graceful shutdown, and startup initialization.

5. SYSTEM LAYERS & AGENT DESIGN

• Layers: API, Mission Controller, Agent Colony, Reasoning Engine, Browser Layer, Vision Layer, Memory Layer, Research Layer, Report Layer, Monitoring. (Never mix responsibilities).
• Required Agents: Commander, Planner, Researcher, Browser, Vision, Memory, Fact Checker, Writer, Summarizer, Evidence Judge, Citation Builder, Reporter, Logger, System Monitor.
• Agent States: Idle, Assigned, Planning, Searching, Browsing, Reading, Reasoning, Discussing, Writing, Reviewing, Completed, Failed, Retrying, Sleeping.