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.