# docsfy

> Self-hosted AI documentation generator that turns Git repositories into searchable static docs through a FastAPI web service.

## Overview

- [Project Overview](project-overview.md): Explain what docsfy does, who it is for, and the high-level problem it solves.
- [Architecture](architecture.md): Describe the FastAPI app, SQLite storage layer, AI generation pipeline, and static site renderer.
- [Core Concepts](core-concepts.md): Define projects, variants, owners, roles, sessions, and generated artifacts.
- [Generation Lifecycle](generation-lifecycle.md): Walk through cloning, planning, page generation, rendering, and ready/error/aborted states.

## Getting Started

- [Prerequisites](prerequisites.md): List Python, uv, git, required AI CLIs/credentials, and mandatory ADMIN_KEY setup.
- [Local Installation](local-installation.md): Show how to install dependencies and run the service locally using the Python project setup.
- [Run with Docker](run-with-docker.md): Document Dockerfile and docker-compose usage, mounted data volume, and health checks.
- [First Documentation Run](first-docs-generation.md): Guide users from login through generating, monitoring, and opening their first docs site.

## Configuration

- [Environment Variables](environment-variables.md): Reference all runtime settings such as ADMIN_KEY, AI provider/model, timeouts, and log level.
- [AI Provider Setup](ai-provider-setup.md): Explain Claude, Gemini, and Cursor provider options, credentials, and model selection behavior.
- [Storage Paths and Data Layout](storage-paths.md): Describe DATA_DIR usage, SQLite DB location, project cache paths, and generated site directories.
- [Session and Cookie Settings](session-cookie-settings.md): Cover secure cookie defaults, SameSite behavior, TTL, and local HTTP development adjustments.
- [Model Discovery and Defaults](model-discovery-and-defaults.md): Explain how known models are learned from ready variants and used in dashboard model pickers.

## Usage Guides

- [Dashboard Workflow](dashboard-workflow.md): Document project listing, filtering, pagination, role-based UI, and generation form behavior.
- [Managing Variants](managing-variants.md): Show how provider/model variants are created, regenerated with force, and deleted safely.
- [Status and Progress Monitoring](status-and-progress.md): Explain the status page, polling behavior, stage updates, activity log, and progress bar semantics.
- [Abort and Retry Flows](abort-and-retry.md): Cover how abort works for active runs and how retry/regeneration works after errors or aborts.
- [View and Download Generated Docs](docs-view-and-download.md): Document variant-specific and latest-variant docs routes plus tar.gz download endpoints.
- [Generated Site Features](generated-site-features.md): Explain search modal, theme toggle, callouts, code copy buttons, TOC, and GitHub metadata.
- [Incremental Regeneration and Cache](incremental-regeneration.md): Describe commit diff detection, page-level cache invalidation, and fallback to full regeneration.

## Administration and Security

- [Authentication Model](authentication-model.md): Detail Bearer token and session-cookie auth flow, public paths, and protected endpoint behavior.
- [Roles and Permissions](roles-and-permissions.md): Define admin, user, and viewer capabilities across UI actions and write-protected APIs.
- [User Management](user-management.md): Document creating users, reserved usernames, deleting users, and admin panel workflows.
- [Project Access Grants](project-access-grants.md): Explain owner-scoped project sharing, grant/revoke APIs, and non-owner visibility rules.
- [API Key Rotation](api-key-rotation.md): Describe self-service and admin-initiated key rotation, validation rules, and session invalidation.
- [Security Controls](security-controls.md): Summarize SSRF checks, path traversal protections, HTML sanitization, and audit logging points.

## API Reference

- [Authentication Endpoints](api-authentication.md): Reference login/logout endpoints, cookie behavior, and auth requirements for API clients.
- [Generation Endpoints](api-generation.md): Document request schema for generation, provider/model validation, and conflict/error responses.
- [Project and Variant Endpoints](api-projects-and-variants.md): List endpoints for status, details, deletion, abort, and downloads across project variants.
- [Admin Endpoints](api-admin.md): Reference user CRUD, access grant/revoke/list endpoints, and admin key rotation operations.
- [Documentation Serving Routes](api-doc-serving.md): Document `/docs` routes for variant-specific and latest-ready documentation file serving.
- [Health and Status Endpoints](api-health-status.md): Describe `/health` and `/api/status` responses for service checks and dashboard polling.

## Operations and Development

- [Deployment Topologies](deployment-topologies.md): Cover local, containerized, and OpenShift-style non-root runtime considerations.
- [Database Schema and Migrations](database-schema-and-migrations.md): Explain projects/users/project_access/sessions tables and built-in migration behavior.
- [Backup and Recovery](backup-and-recovery.md): Provide guidance for backing up SQLite and generated project artifacts under DATA_DIR.
- [Testing and Quality Gates](testing-and-quality-gates.md): Document pytest coverage areas, tox usage, pre-commit hooks, mypy, ruff, and secrets scanning.
- [CI/CD Integration](ci-cd-integration.md): Describe current automation posture and recommend pipeline steps based on existing tox and hooks.
- [Repository Structure](repository-structure.md): Map source modules, templates, static assets, tests, and runtime/config files for contributors.
- [Extending docsfy](extending-docsfy.md): Show where to customize prompts, renderer templates, frontend assets, and generation logic.