Wingfix is a retrieval-augmented generation (RAG) system designed for Aircraft Maintenance Engineers (AMEs) to quickly find accurate information from aviation technical documentation with proper effectivity filtering and citation tracking.

• 📚 Multi-Source Document Ingestion: Supports AMM, IPC, WDM, CMM, MEL, and internal policies (Comply365)
• 🔍 Hybrid Search: Combines text and vision-based retrieval for comprehensive results
• ✈️ Effectivity Filtering: Ensures answers are valid for specific tail numbers, dates, and fleet configurations
• 📎 Citation Tracking: Every answer includes document revision, figure, and effectivity information
• 🔄 Precedence Resolution: Automatically prioritizes internal policies over OEM documentation
• 📦 Inventory Integration: Simulated TRAX integration for part availability checking
• ⚠️ CMM Handling: Clearly marks uncontrolled/legacy documents with acknowledgment requirements

┌─────────────────────────────────────────────────────────────────────────┐
│                           Wingfix Architecture                          │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐                │
│  │   FastAPI    │   │  LangGraph   │   │   Ollama       │                │
│  │   REST API   │──▶│   Agents     │──▶│   LLM/VLM    │                │
│  └──────────────┘   └──────────────┘   └──────────────┘                │
│         │                  │                                            │
│         ▼                  ▼                                            │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐                │
│  │   Qdrant     │   │  PostgreSQL  │   │    MinIO     │                │
│  │   Vectors    │   │   Metadata   │   │   Objects    │                │
│  └──────────────┘   └──────────────┘   └──────────────┘                │
└─────────────────────────────────────────────────────────────────────────┘

The fastest way to get started:

# 1. Drop your PDF manuals into data/incoming/
mkdir -p data/incoming
cp /path/to/your/manuals/*.pdf data/incoming/

# 2. Start everything with one command
./wingfix-start

# 3. Open http://localhost:5173 in your browser (React PWA)
#    Stop with: ./wingfix-stop or Ctrl+C

That's it! The start script automatically handles:

• Virtual environment activation
• Docker infrastructure (PostgreSQL, Qdrant, MinIO, Redis)
• Database migrations
• Qdrant collection initialization
• Ollama LLM server
• WingFix API server
• React PWA frontend (Vite dev server on port 5173)
• Document ingestion from data/incoming/

./wingfix-start                    # Start with React PWA (default)
./wingfix-start --cli              # Start with interactive CLI
./wingfix-start --no-browser       # Start React PWA but skip auto-opening browser
./wingfix-start --no-ingest        # Skip document ingestion
./wingfix-start --no-cli           # Start services only (no UI)
./wingfix-start --skip-migrations  # Skip database migrations
./wingfix-start --help             # Show all options

• Python 3.11 or higher
• Node.js 18 or higher (for React PWA frontend)
• Docker and Docker Compose
• NVIDIA GPU with CUDA support (for model inference)
• 96GB GPU VRAM recommended (dual RTX A6000 or equivalent) for Gemma 4 31B Instruct (Q4_K_M quantized, 256k context)

If you prefer manual setup or need more control:

1. Clone the repository:

   git clone https://github.com/wingfix/wingfix.git
   cd wingfix

2. Create a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

   # For development (includes testing and code quality tools)
   pip install -e ".[dev]"
   
   # Or use requirements files for pinned versions
   pip install -r requirements-dev.txt

4. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration

5. Start infrastructure services:

   # Using the convenience script (recommended)
   ./scripts/start-infra.sh
   
   # Or using Docker Compose directly
   docker compose up -d
   
   # Verify services are healthy
   ./scripts/docker-health-check.sh

   This starts:

   • PostgreSQL 16: Metadata store (port 5432)
   • Qdrant: Vector database (ports 6333/6334)
   • MinIO: Object storage (ports 9000/9001)
   • Redis: Caching layer (port 6379)

6. Run database migrations:

   alembic upgrade head

7. Start the API server:

   uvicorn wingfix.api.main:app --reload --port 8082

Set up pre-commit hooks for code quality:

pre-commit install

# Run on all files
pre-commit run --all-files

wingfix/
├── src/
│   ├── wingfix/
│   │   ├── __init__.py
│   │   ├── ingestion/      # Document ingestion pipeline
│   │   ├── enrichment/     # Entity extraction & enrichment
│   │   ├── storage/        # Database & storage layer
│   │   ├── indexing/       # Embedding & indexing
│   │   ├── retrieval/      # Search & retrieval
│   │   ├── agents/         # LangGraph agentic workflows
│   │   ├── api/            # FastAPI endpoints
│   │   └── utils/          # Utilities & helpers
│   └── tests/              # Test suite
├── configs/
│   ├── postgres/
│   │   └── init.sql        # PostgreSQL initial schema
│   ├── qdrant/
│   │   └── config.yaml     # Qdrant configuration
│   └── minio/
│       └── policy.json     # MinIO bucket policies
├── scripts/
│   ├── wingfix-start.sh    # One-command startup (all services)
│   ├── wingfix-stop.sh     # One-command shutdown
│   ├── start-infra.sh      # Start Docker services only
│   ├── stop-infra.sh       # Stop Docker services only
│   ├── start_ollama.sh     # Start Ollama server
│   ├── init_qdrant.py      # Initialize Qdrant collections
│   └── docker-health-check.sh  # Verify service health
├── data/                   # Data directory (gitignored)
├── docs/                   # Documentation
├── pyproject.toml          # Project configuration
├── requirements.txt        # Pinned dependencies
├── docker-compose.yml      # Infrastructure services
├── docker-compose.override.yml.example  # Dev overrides template
└── README.md

Wingfix uses a hierarchical configuration system:

1. Environment Variables: Override all other settings
2. Config Files: configs/local.yaml overrides configs/default.yaml
3. Defaults: Built-in sensible defaults

Key configuration sections:

• Database: PostgreSQL, Qdrant, MinIO connections
• Models: Unified multimodal LLM (Gemma 4 31B Instruct) and embedding model paths
• Ingestion: Watch directories and supported formats
• Agent: Confidence thresholds, retry settings, and multi-step reasoning parameters

See .env.example for all available configuration options.

# Run all tests
pytest

# Run with coverage
pytest --cov=wingfix --cov-report=html

# Run specific test file
pytest src/tests/unit/test_pn_extractor.py

# Run only fast tests (skip slow/integration)
pytest -m "not slow and not integration"

# Format code
black src/
ruff check --fix src/

# Type checking
mypy src/wingfix/

# All checks via pre-commit
pre-commit run --all-files

# Create a new migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

# Rollback one migration
alembic downgrade -1

• Agent Framework: LangGraph, LlamaIndex
• LLM Serving: Ollama
• Vector Database: Qdrant
• Relational Database: PostgreSQL with SQLAlchemy
• Object Storage: MinIO (S3-compatible)
• API Framework: FastAPI
• Embedding Models: bge-m3 (text), SigLIP (vision)

• Development Guide
• Architecture Overview
• API Documentation
• Operations Runbook

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes with tests
4. Run pre-commit hooks: pre-commit run --all-files
5. Commit your changes: git commit -m "Add my feature"
6. Push to the branch: git push origin feature/my-feature
7. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

For questions or issues, please open a GitHub issue or contact the development team.

Built with ❤️ for Aircraft Maintenance Engineers