| # DeepBoner Documentation |
|
|
| Welcome to the DeepBoner documentation. This directory contains comprehensive documentation for developers, contributors, and operators. |
|
|
| ## Quick Navigation |
|
|
| | Need to... | Go to... | |
| |------------|----------| |
| | Get started quickly | [Getting Started](getting-started/installation.md) | |
| | Understand the architecture | [Architecture Overview](architecture/overview.md) | |
| | Assess production readiness | [Production Readiness](architecture/production-readiness.md) | |
| | Set up for development | [Development Guide](development/testing.md) | |
| | Deploy the application | [Deployment Guide](deployment/docker.md) | |
| | Look up configuration | [Reference](reference/configuration.md) | |
| | Track technical debt | [Technical Debt](technical-debt/index.md) | |
|
|
| ## Documentation Structure |
|
|
| ``` |
| docs/ |
| ├── README.md # This file - documentation index |
| │ |
| ├── getting-started/ # Onboarding documentation |
| │ ├── installation.md # Installation guide |
| │ ├── quickstart.md # 5-minute quickstart |
| │ ├── configuration.md # Configuration guide |
| │ └── troubleshooting.md # Common issues and solutions |
| │ |
| ├── architecture/ # System design documentation |
| │ ├── overview.md # High-level architecture |
| │ ├── agent-tool-state-contracts.md # Agent/Tool/State contracts (CRITICAL) |
| │ ├── production-readiness.md # Enterprise gap analysis (HONEST) |
| │ ├── system-registry.md # Service registry (canonical wiring) |
| │ ├── workflow-diagrams.md # Visual workflow diagrams |
| │ ├── component-inventory.md # Complete component catalog |
| │ ├── data-models.md # Pydantic model documentation |
| │ └── exception-hierarchy.md # Exception types and handling |
| │ |
| ├── development/ # Developer guides |
| │ ├── testing.md # Testing strategy and patterns |
| │ ├── code-style.md # Code style and conventions |
| │ └── release-process.md # Release workflow |
| │ |
| ├── deployment/ # Deployment documentation |
| │ ├── docker.md # Docker deployment |
| │ ├── huggingface-spaces.md # HuggingFace Spaces deployment |
| │ └── mcp-integration.md # MCP server setup |
| │ |
| ├── technical-debt/ # Known issues and improvements |
| │ ├── index.md # Technical debt overview |
| │ └── debt-registry.md # Itemized debt tracking |
| │ |
| ├── reference/ # API and configuration reference |
| │ ├── configuration.md # All configuration options |
| │ └── environment-variables.md # Environment variable reference |
| │ |
| ├── bugs/ # Bug tracking (existing) |
| │ ├── active-bugs.md |
| │ └── p3-progress-bar-positioning.md |
| │ |
| ├── decisions/ # Architecture Decision Records (existing) |
| │ └── 2025-11-27-pr55-evaluation.md |
| │ |
| └── future-roadmap/ # Future feature specs (existing) |
| └── 16-pubmed-fulltext.md |
| ``` |
|
|
| ## Documentation Standards |
|
|
| ### File Naming |
| - Use **kebab-case** for all filenames (e.g., `getting-started.md`) |
| - Keep names descriptive but concise |
|
|
| ### Content Guidelines |
| - Start each document with a clear title and purpose |
| - Include a table of contents for longer documents |
| - Use Mermaid diagrams for visual documentation |
| - Link to related documentation |
| - Keep content current - update when code changes |
|
|
| ### Markdown Conventions |
| - Use ATX-style headers (`#`, `##`, etc.) |
| - Code blocks with language specification |
| - Tables for structured data |
| - Admonitions for warnings/notes (where supported) |
|
|
| ## Key Documents |
|
|
| ### For New Developers |
| 1. [Installation](getting-started/installation.md) - Set up your environment |
| 2. [Quickstart](getting-started/quickstart.md) - Run your first query |
| 3. [Architecture Overview](architecture/overview.md) - Understand the system |
| 4. [Testing](development/testing.md) - Run and write tests |
|
|
| ### For Contributors |
| 1. [CONTRIBUTING.md](../CONTRIBUTING.md) - Contribution guidelines |
| 2. [Code Style](development/code-style.md) - Style conventions |
| 3. [Testing](development/testing.md) - Testing requirements |
|
|
| ### For Operators |
| 1. [Docker Deployment](deployment/docker.md) - Container deployment |
| 2. [HuggingFace Spaces](deployment/huggingface-spaces.md) - Cloud deployment |
| 3. [Configuration Reference](reference/configuration.md) - All options |
|
|
| ### For Understanding the Codebase |
| 1. [Agent-Tool-State Contracts](architecture/agent-tool-state-contracts.md) - **CRITICAL** - Agent coordination contracts |
| 2. [Component Inventory](architecture/component-inventory.md) - All modules |
| 3. [Data Models](architecture/data-models.md) - Core types |
| 4. [System Registry](architecture/system-registry.md) - Service wiring |
| 5. [Technical Debt](technical-debt/index.md) - Known issues |
|
|
| ## Related Documentation |
|
|
| - **[README.md](../README.md)** - Project overview and quick start |
| - **[CLAUDE.md](../CLAUDE.md)** - AI agent developer reference |
| - **[CHANGELOG.md](../CHANGELOG.md)** - Release history |
| - **[SECURITY.md](../SECURITY.md)** - Security policy |
| - **[CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)** - Community guidelines |
|
|
| ## Contributing to Documentation |
|
|
| Documentation is code. Please: |
|
|
| 1. Keep docs updated when changing related code |
| 2. Follow the naming and style conventions |
| 3. Test links before committing |
| 4. Add new documents to this index |
|
|
| See [CONTRIBUTING.md](../CONTRIBUTING.md) for full guidelines. |
|
|
| --- |
|
|
| *"Well-documented boners only. We take evidence-based documentation very seriously."* 📚 |
|
|
