64 lines (45 loc) · 3.07 KB

DeepSQL Documentation

Technical documentation for DeepSQL. Start with the root README.md for a project overview and the fastest path to a running instance.

Setup & Getting Started

QUICKSTART.md — Quick start guide to get up and running
SETUP.md — Complete installation and configuration guide
root/SELF_HOST_GUIDE.md — Production self-hosting operations: sizing, environment reference, first-run access, TLS, upgrades, backups
RAG_SETUP.md — Configure RAG for natural language SQL generation
RAG_TRAINING.md — Training the retrieval layer on your schema
AZURE-AI-SEARCH.md — Optional Azure AI Search vector backend

Architecture & Design

DESIGN.md — Product and system design
SERVICES.md — Backend service map
BRAIN-design.md — Schema-intelligence design notes
root/CLAUDE.md — Full architecture and development guide
root/AGENTS.md — High-level codebase map for AI agents
API_CLIENT_USAGE.md — Centralized frontend API client

Chat, Memory & Guardrails

CHAT_MEMORY_AND_GUARDRAILS.md — How chat memory, RAG, and SQL guardrails fit together
TOOL_AWARE_CHAT_MEMORY.md — Spring AI JDBC chat memory behavior and troubleshooting

CLI & MCP

public/cli-and-mcp.md — The deepsql CLI and MCP server
root/MCP_PHASE1.md — MCP server tools, configuration, and env vars

Feature Documentation

DATABASE_ADVISOR.md — AI-powered database optimization advisor
DATABASE_ADVISOR_UI.md — Advisor UI implementation details
EXPLAIN_HISTORY_FEATURE.md — EXPLAIN plan history tracking
PERFORMANCE_UI_IMPLEMENTATION.md — Performance dashboard implementation
PERFORMANCE_UI_BUGFIXES.md — Performance UI fixes and improvements
RBAC_USAGE_GUIDE.md — Roles, permissions, and access control

Operations

LOGGING-GUIDE.md — Log format and what to look for

Design Notes & Plans

Historical design documents. These record intent at a point in time and may lag the code.

Contributing

When adding new documentation:

Use clear, descriptive filenames in UPPERCASE with underscores
Include a brief summary at the top of each document
Update this index
Link to related documents where appropriate