README.md

Documentation

Complete documentation for askdocs-rag-agent.

---

Structure

docs/
├── README.md                    # This file
│
├── core/                        # Shared technical docs
│   ├── architecture/            # System design
│   ├── security/                # Security guidelines
│   ├── deployment/              # Cloud deployment
│   └── configuration/           # Environment config
│
├── interfaces/                  # How to use (each interface)
│   ├── web-ui/                  # Web interface
│   ├── api/                     # REST API integration
│   ├── slack-bot/               # Slack integration
│   └── mcp/                     # Claude Desktop
│
├── features/                    # What it does
├── development/                 # For developers
├── business/                    # For sales
├── project/                     # Planning
├── testing/                     # Testing
└── getting-started/             # Quick start

---

Quick Navigation

Getting Started

New user? Start here:

1. getting-started/WHY.md - Why use this?
2. getting-started/LOCAL_DEVELOPMENT.md - Run locally
3. Choose interface - Pick how to use it

---

Core (Reusable Docs)

Architecture & Design:

• core/architecture/ARCHITECTURE.md - System design
• core/architecture/DATABASE_SCHEMA.md - Database design
• core/architecture/API.md - API technical spec

Security:

• core/security/README.md - Security overview
• core/security/AUTHENTICATION.md - API keys, auth
• core/security/SECRETS_MANAGEMENT.md - Secrets handling

Deployment:

• core/deployment/DEPLOYMENT.md - Overview
• core/deployment/GCP.md - Google Cloud Run
• core/deployment/AZURE.md - Azure Container Apps

Configuration:

• core/configuration/CONFIGURATION.md - All env vars

---

Interfaces (How to Use)

Pick how you want to use AskDocs:

Web UI - Browser interface

• For: End users, demos
• Setup: 5 minutes
• Use: Upload PDF, ask questions in browser

REST API - Programmatic integration

• For: Developers integrating into apps
• Setup: 10 minutes
• Use: HTTP requests from your code

Slack Bot - Ask in Slack

• For: Teams using Slack
• Setup: 15 minutes
• Use: @askdocs your question

MCP/Claude Desktop - AI assistant integration

• For: Claude Desktop users
• Setup: 10 minutes
• Use: Ask Claude to search your docs

---

Testing

Backend (pytest) - Unit & Integration Tests:

• testing/README.md - Python API testing (71 tests)
  • Tests: Retrieval, reranking, semantic chunking, table extraction
  • Providers: Mock (fast) or Ollama (real LLM)
  • Quick start: pytest app/tests/ -v

Frontend (Playwright) - E2E Tests:

• e2e-testing/README.md - Web UI browser testing (23 tests)
  • Tests: User flows, document upload, chat, citations
  • Providers: Mock, Ollama, or Gemini
  • Quick start: cd web-ui && ./run-e2e-with-ollama.sh

Developer Resources:

• development/TESTING_AND_SCRIPTS.md - Quick reference
• development/SHELL_SCRIPTS.md - Shell script best practices

---

Features

What the product does:

• Document Ingestion
• Grounded Q&A
• Document Management
• Multi-turn Chat
• Query Routing
• MCP Integration
• Evaluation

---

Development

For developers building features:

• development/DEVELOPMENT.md - Dev workflow
• development/PROMPTS.md - LLM prompts
• development/EVALUATION_PLAN.md - Quality metrics
• development/SCHEMA_GENERATION.md - Auto-generate DB schema docs
• development/SCHEMA_COMMANDS.md - Quick reference for DB commands

---

Business

For sales and marketing:

• business/ONE_PAGER.md - Product pitch
• business/PRICING.md - Plans and pricing
• business/CASE_STUDIES.md - Customer examples
• business/ROI_CALCULATOR.md - Financial justification

---

Project

Planning and research:

• project/PRE_CODE_CHECKLIST.md - Implementation roadmap
• project/MARKET_RESEARCH.md - Market analysis

---

Testing

Quality assurance:

• testing/TESTING.md - How to test

---

By Role

End User

1. Pick interface: Web UI or Slack
2. Upload documents
3. Ask questions

Developer

1. getting-started/LOCAL_DEVELOPMENT.md - Setup
2. interfaces/api/ - Integration guide
3. development/DEVELOPMENT.md - Dev workflow

DevOps

1. core/deployment/ - Deployment guides
2. core/security/ - Security setup
3. core/configuration/ - Configuration

Business

1. business/ONE_PAGER.md - Product overview
2. business/PRICING.md - Pricing
3. business/CASE_STUDIES.md - Examples

---

File Count

Category	Count	Location
Core (shared)	10	/docs/core/**/*.md
Interfaces	4	/docs/interfaces/**/*.md
Features	7	/docs/features/*.md
Development	3	/docs/development/*.md
Business	5	/docs/business/*.md
Project	2	/docs/project/*.md
Testing	1	/docs/testing/*.md
Getting Started	2	/docs/getting-started/*.md
Total	34 files	All organized

---

Key Concept: Core vs Interfaces

Core docs are reusable across ALL interfaces:

• Security → used by web-ui, API, Slack, MCP
• Deployment → used by all interfaces
• Configuration → used by all interfaces

Interface docs are specific to each way of using:

• Web UI → browser setup, customization
• API → integration code examples
• Slack → bot setup, commands
• MCP → Claude Desktop config

This avoids duplication. Each interface references core docs.

---

Contributing

Found an issue or want to improve docs?

1. Open GitHub issue with label documentation
2. Or submit a PR

Questions? See main README