Gavlix Docs

Universal documentation engine for software repositories. Scans source files, understands structure, and generates architecture documentation, workflow diagrams, API notes, and developer guidance.

1. Overview

Gavlix Docs is a universal CLI tool that works on any codebase regardless of framework or structure. It behaves like eslint, prettier, and black — detecting patterns dynamically and generating complete documentation without hardcoding assumptions about Flask, Django, React, Next.js, or any specific framework.

Problem It Solves

Understanding a new codebase is expensive. Gavlix Docs turns repository structure into clear documentation that developers, reviewers, and AI agents can consume without manually reading every file.

Supported Languages

• Python (AST-based parsing)
• JavaScript / TypeScript (regex-based parsing)
• HTML / CSS
• JSON / YAML
• SQL (DDL parsing)
• Markdown

2. Features

• ✅ Auto documentation — Generates root README, module READMEs, and detailed docs
• ✅ Architecture diagrams — Mermaid diagrams for dependency, workflow, database, and architecture
• ✅ Database analysis — ORM detection (SQLAlchemy, Django, Tortoise, Peewee, Pony, SQLModel), table mapping, relationship detection
• ✅ Plugin system — Auto-registration, isolation, install/remove/list
• ✅ Incremental analysis — File hashing, change detection, cache reuse
• ✅ Dry-run mode — Preview changes without writing files
• ✅ Error isolation — Parse failures skip files safely, never crash
• ✅ Strict validation — Enforces completeness before finishing
• ✅ VS Code integration — Commands, sidebar, output panel
• ✅ HTTP API — FastAPI server for VS Code and web dashboard integration

3. Installation

From PyPI

pip install gavlix-docs

From Source

git clone https://github.com/gavlix/gavlix-docs.git
cd gavlix-docs
pip install -e ".[dev]"

Verify Installation

gavlix-docs --version

4. Usage

Generate Documentation

gavlix-docs generate .

Generate documentation for the current directory. Creates:

• README.md — Root system documentation
• docs/ — Detailed documentation (architecture, database, security, deployment, API, workflows)
• docs/adr/ — Architecture Decision Records
• diagrams/ — Mermaid diagram source files
• modules/<name>/README.md — Per-module documentation

Analyze Without Writing

gavlix-docs analyze .

Analyze repository structure without generating documentation files.

Validate Documentation

gavlix-docs validate .

Validate that all required documentation files and sections exist.

Watch Mode

gavlix-docs watch .

Monitor file changes and automatically update documentation.

Dry Run

gavlix-docs generate . --dry-run

Preview what files would be written without actually writing them.

Strict Mode

gavlix-docs generate . --strict

Fail if validation finds any missing documentation.

Disable Cache

gavlix-docs generate . --no-cache

Force fresh analysis without using cached results.

Start API Server

gavlix-docs serve

Start the FastAPI server for VS Code extension and web dashboard integration.

Plugin Management

gavlix-docs plugin list
gavlix-docs plugin install <name>
gavlix-docs plugin remove <name>

5. Configuration

Create a gavlix.config.yaml in your project root:

ignore:
  - node_modules
  - .git
  - dist
  - .next

entry_points:
  - app.py
  - main.ts

documentation:
  strict: true
  include_private: false

analysis:
  incremental: true

database:
  orm: auto-detect

diagrams:
  enabled: true
  format: mermaid

plugins:
  enabled: true
  directory: .gavlix/plugins

6. VS Code Extension

Installation

1. Install the VS Code extension from the marketplace (search "Gavlix Docs")
2. Or build from source:

cd extensions/vscode-extension
npm install
npm run compile
vsce package

Commands

Command	Description
gavlix.generateDocs	Generate documentation for the workspace
gavlix.analyzeProject	Analyze project structure
gavlix.validateDocs	Validate documentation completeness
gavlix.watchDocs	Watch and auto-update documentation
gavlix.stopWatch	Stop watch mode

Configuration

{
  "gavlix.useApi": false,
  "gavlix.apiUrl": "http://127.0.0.1:8000",
  "gavlix.strict": false,
  "gavlix.outputDir": "docs_output"
}

7. Plugin Development

Plugin Interface

export interface GavlixPlugin {
  name: string;
  version: string;
  analyzers?: Analyzer[];
  generators?: Generator[];
}

Python Plugin SDK

from plugins.sdk import BasePlugin, PluginMetadata

class MyPlugin(BasePlugin):
    def __init__(self):
        super().__init__(PluginMetadata(
            name="my-plugin",
            version="1.0.0",
            description="Custom analyzer plugin",
            capabilities=["analyzer"],
        ))

    def run(self, context):
        # Custom analysis logic
        return {"status": "ok", "result": "custom analysis"}

Install a Plugin

gavlix-docs plugin install my-plugin

8. Architecture Overview

Pipeline Flow

Scan Project → Parse All Files → Build Code Model → Build Dependency Graph
    ↓
Detect Entry Points → Infer Workflows → Analyze Database Layer
    ↓
Analyze Security Layer → Analyze Deployment Layer
    ↓
Generate Diagrams → Generate Documentation → Validate Completeness
    ↓
Write Files

Architecture Diagram

graph TB
    A[CLI / API / VS Code] --> B[GavlixOrchestrator]
    B --> C[ProjectAnalyzer]
    C --> D[ArchitectureMapper]
    D --> E[DependencyMapper]
    B --> F[DatabaseAnalyzer]
    B --> G[SecurityAnalyzer]
    B --> H[DeploymentAnalyzer]
    B --> I[WorkflowBuilder]
    B --> J[Generators]
    J --> K[ReadmeGenerator]
    J --> L[ModuleReadmeGenerator]
    J --> M[DiagramGenerator]
    J --> N[DocumentationBundle]
    B --> O[DocumentationValidator]
    O --> P[SafeWriter]
    P --> Q[Output Files]

Why This Architecture

• Modular: Each analyzer, generator, and validator is independent
• Scalable: Incremental analysis with file hashing and caching
• Language-agnostic: Parsers are pluggable per file extension
• Error-isolated: Parse failures skip files, never crash the system
• Extensible: Plugin system with auto-registration and isolation

Key Components

Component	Purpose
gavlix_docs/cli.py	CLI with isolated command handlers, exit codes, error handling
gavlix_docs/orchestrator.py	Coordinates the full pipeline
gavlix_docs/analyzers/	Project analysis and structure discovery
gavlix_docs/generators/	Markdown and Mermaid output generation
gavlix_docs/validators/	Output validation and completeness checks
gavlix_docs/cache/	Disk-based cache with file-level change detection
gavlix_docs/config/	Configuration loading and validation
gavlix_docs/plugins.py	Plugin registry with auto-registration and isolation
gavlix_docs/api.py	FastAPI server for VS Code and web integration

9. API

The FastAPI server exposes:

Method	Route	Description
GET	/health	Health check
GET	/status	System status with validation result
POST	/analyze	Analyze a project
POST	/generate	Generate documentation
GET	/api/overview	Project overview with statistics
GET	/api/modules	List all modules
GET	/api/graph	Dependency graph
GET	/api/workflows	Inferred workflows
GET	/api/database	Database schema
GET	/api/security	Security findings
GET	/api/deployment	Deployment info
GET	/api/metrics	System metrics

10. Testing

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=gavlix_docs

# Run specific test file
pytest tests/test_cli.py

11. License

MIT License — see LICENSE.