The-AI-Alliance · andrewmusselman · Feb 5, 2026
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,92 @@
+# Gofannon Documentation
+
+Gofannon is an open-source platform for rapidly prototyping AI agents and their web UIs. Build agent flows, preview interactions, and deploy—without framework lock-in.
+
+## Quick Links
+
+| I want to... | Go to... |
+|--------------|----------|
+| Get started using Gofannon | [Quickstart Guide](quickstart/README.md) |
+| Set up a dev environment | [Developer Setup](developers-quickstart.md) |
+| Configure LLM providers | [LLM Configuration](llm-provider-configuration.md) |
+| Set up a database | [Database Guide](database/README.md) |
+| Run tests | [Testing Guide](testing/README.md) |
+| Understand the API | [API Reference](api.md) |
+
+## Getting Started
+
+- **[Quickstart Guide](quickstart/README.md)** - Install Gofannon with Docker and create your first agent in 5 minutes.
+
+- **[Developer Setup](developers-quickstart.md)** - Set up a local development environment for contributing.
+
+## Configuration
+
+- **[LLM Provider Configuration](llm-provider-configuration.md)** - Configure OpenAI, Anthropic, Gemini, Bedrock, and other providers. Covers model parameters, extended thinking, and adding new providers.
+
+- **[API Key Management](api-key-management.md)** - User-specific API keys and the key priority system.
+
+- **[Database Guide](database/README.md)** - Set up CouchDB, Firestore, DynamoDB, or in-memory storage.
+  - [Configuration](database/configuration.md) - Environment variables and provider setup
+  - [Schema](database/schema.md) - Document structures and collections
+  - [Troubleshooting](database/troubleshooting.md) - Common issues and solutions
+
+## Features
+
+- **[Agent Data Store](data-store.md)** - Persistent key-value storage for agents to save and share data across executions.
+
+## Reference
+
+- **[API Reference](api.md)** - HTTP API documentation for the user-service backend.
+
+- **[Observability](observability.md)** - Logging, tracing, and monitoring.
+
+## Development
+
+- **[Testing Guide](testing/README.md)** - Running unit, integration, and E2E tests.
+  - [Unit Testing](testing/unit-testing.md) - Detailed patterns and examples
+  - [Backend Testing](testing/backend-testing.md) - Python/pytest guide
+  - [Frontend Testing](testing/frontend-testing.md) - React/Vitest guide
+  - [Integration Testing](testing/integration-testing.md) - Multi-component and E2E tests
+  - [CI/CD](testing/ci-cd.md) - GitHub Actions and coverage
+  - [Contributing Tests](testing/contributing.md) - PR requirements
+
+- **[Extension Example](EXTENSION_EXAMPLE.md)** - How to add custom pages, cards, and API endpoints.
+
+- **[LLM Service](developers/llm-service.md)** - Architecture of the centralized LLM service, cost tracking, and why all LLM calls must go through it.
+
+- **[Website Development](developers/website.md)** - Building the Docusaurus marketing website.
+
+- **[Architecture](architecture.md)** - System design overview.
+
+## About
+
+- **[Why "Gofannon"?](about-name-origin.md)** - The story behind our Celtic deity namesake.
+
+- **[Roadmap](roadmap.md)** - Planned features and design discussions.
+
+## Project Structure
+
+```
+gofannon/
+├── webapp/
+│   ├── packages/
+│   │   ├── api/user-service/    # Python FastAPI backend
+│   │   ├── webui/               # React frontend
+│   │   └── config/              # Shared configuration
+│   ├── infra/
+│   │   ├── docker/              # Docker Compose setup
+│   │   └── firebase/            # Firebase deployment
+│   └── tests/e2e/               # Playwright E2E tests
+├── docs/                        # This documentation
+└── website/                     # Marketing site
+```
+
+## Getting Help
+
+- **Issues**: [Report bugs or request features](https://github.com/The-AI-Alliance/gofannon/issues)
+- **Discussions**: [Ask questions](https://github.com/The-AI-Alliance/gofannon/discussions)
+- **Contributing**: See [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+## License
+
+Apache 2.0 - See [LICENSE](../LICENSE)
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,19 +1,210 @@
-# Architecture / Services
+# Architecture
 
-This page provides an overview of the Gofannon architecture and its core services.
+Gofannon is designed as a modular system for rapidly prototyping AI agents and their associated web UIs.
 
-## Overview
+## System Overview
 
-Gofannon is designed as a modular system for rapidly prototyping AI agents and their associated web UIs.
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Web Browser                              │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      React Frontend                              │
+│                    (webapp/packages/webui)                       │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
+│  │ Agent Editor│  │  Sandbox    │  │    Chat Interface       │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
+└─────────────────────────┬───────────────────────────────────────┘
+                          │ HTTP/REST
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Python API (FastAPI)                          │
+│               (webapp/packages/api/user-service)                 │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
+│  │ LLM Service │  │ User Service│  │   Database Service      │  │
+│  └──────┬──────┘  └─────────────┘  └───────────┬─────────────┘  │
+│         │                                       │                │
+└─────────┼───────────────────────────────────────┼────────────────┘
+          │                                       │
+          ▼                                       ▼
+┌─────────────────────┐               ┌─────────────────────────┐
+│    LLM Providers    │               │       Database          │
+│  (via LiteLLM)      │               │  (CouchDB/Firestore/    │
+│                     │               │   DynamoDB/Memory)      │
+│  • OpenAI           │               └─────────────────────────┘
+│  • Anthropic        │
+│  • Google Gemini    │
+│  • AWS Bedrock      │
+│  • Ollama           │
+└─────────────────────┘
+```
+
+## Core Components
+
+### Frontend (React)
+
+**Location:** `webapp/packages/webui/`
+
+- **Framework:** React + Vite + Material-UI
+- **State:** React hooks and context
+- **Routing:** React Router
+- **Build:** pnpm
+
+Key features:
+- Agent editor with code generation
+- Sandbox for testing agents
+- Chat interface for deployed agents
+- Demo gallery
+
+### Backend API (FastAPI)
+
+**Location:** `webapp/packages/api/user-service/`
+
+- **Framework:** FastAPI (Python 3.10+)
+- **Server:** Uvicorn (ASGI)
+- **Auth:** Firebase Authentication (or mock for development)
+
+Key modules:
+
+| Module | Purpose |
+|--------|---------|
+| `routes.py` | HTTP endpoint definitions |
+| `dependencies.py` | Dependency injection, sandbox execution |
+| `services/llm_service.py` | LLM provider abstraction via LiteLLM |
+| `services/user_service.py` | User profiles, billing, API keys |
+| `services/database_service/` | Pluggable database backends |
+| `agent_factory/` | Agent code generation |
+| `models/` | Pydantic models for data validation |
+| `config/` | Provider configuration and settings |
+
+### Agent Sandbox
+
+Agents run in an isolated execution environment:
+
+```python
+# Simplified sandbox execution flow
+async def execute_agent(agent_code: str, input_data: dict, user_id: str):
+    # 1. Create isolated globals
+    exec_globals = {
+        "tools": available_tools,
+        "data_store": DataStoreProxy(user_id),
+        "call_llm": llm_service.call_llm,
+    }
+
+    # 2. Execute agent code
+    exec(agent_code, exec_globals)
+
+    # 3. Call the agent's run function
+    result = await exec_globals["run"](input_data, exec_globals["tools"])
+
+    return result
+```
+
+### LLM Service
+
+All LLM calls go through `services/llm_service.py`:
+
+```python
+from services.llm_service import call_llm
+
+response = await call_llm(
+    model="claude-sonnet-4-20250514",
+    messages=[{"role": "user", "content": "Hello"}],
+    user_id=user_id,
+    tools=available_tools,
+)
+```
+
+Benefits:
+- **Unified interface** for all providers (OpenAI, Anthropic, etc.)
+- **Cost tracking** per user
+- **Observability** logging
+- **Extended thinking** support
+
+See [LLM Provider Configuration](llm-provider-configuration.md) for details.
+
+### Database Service
+
+Pluggable database abstraction:
+
+```python
+from services.database_service import get_database_service
+
+db = get_database_service(settings)
+doc = db.get("agents", agent_id)
+db.save("agents", agent_id, updated_doc)
+```
+
+Supported backends:
+- In-Memory (development)
+- CouchDB (self-hosted)
+- Firestore (Google Cloud)
+- DynamoDB (AWS)
+
+See [Database Guide](database/README.md) for details.
+
+## Data Flow
+
+### Agent Creation
+
+1. User defines agent in web UI (name, description, tools, models)
+2. Frontend sends configuration to `/api/agents/generate-code`
+3. Agent factory generates Python code from prompt + configuration
+4. User tests in sandbox
+5. User saves agent to database
+6. User deploys agent (creates friendly URL mapping)
+
+### Agent Execution
+
+1. Request arrives at `/api/agents/{agent_name}/run`
+2. Backend loads agent code from database
+3. Sandbox executes agent with:
+   - Input data from request
+   - Available tools
+   - Data store proxy
+   - LLM service
+4. Agent calls tools, LLM, and data store as needed
+5. Result returned to caller
+
+### Chat Sessions
+
+1. User starts chat with deployed agent
+2. Session created in database
+3. Each message:
+   - Appended to session history
+   - Agent invoked with full context
+   - Response appended to history
+4. Session persists for future retrieval
+
+## Extension Points
+
+### Custom API Endpoints
+
+See [Extension Example](EXTENSION_EXAMPLE.md) for adding:
+- Custom API routes
+- Custom UI pages
+- Custom home page cards
+
+### Custom Database Backends
+
+See [Database Guide](database/README.md#implementing-a-new-database) for adding new storage backends.
 
-## Core Services
+### Custom LLM Providers
 
-*Documentation coming soon...*
+See [LLM Provider Configuration](llm-provider-configuration.md#adding-a-new-provider) for adding new model providers.
 
-## System Architecture
+## Deployment Options
 
-*Detailed architecture diagrams and descriptions will be added here.*
+| Target | Configuration |
+|--------|---------------|
+| Docker Compose | `webapp/infra/docker/` |
+| Firebase | `webapp/infra/firebase/` |
+| Kubernetes | Planned |
 
-## Service Interactions
+## Related Documentation
 
-*Information about how services communicate and interact will be documented here.*
+- [Quickstart](quickstart/README.md) - Get running in 5 minutes
+- [Developer Setup](developers-quickstart.md) - Local development environment
+- [API Reference](api.md) - HTTP endpoints
diff --git a/docs/contact-community.md b/docs/contact-community.md