Watchtower

AI-powered developer observability and knowledge platform

Watchtower watches not just code, but your workflows, pipelines, and logs. It generates AI-powered, real-time, structured documentation that acts as a project's memory and guide — reducing friction, improving onboarding, and surfacing actionable insights across the entire development lifecycle.

Features

• File Watching - Real-time monitoring of code changes
• Vector Search - Semantic search across your codebase using embeddings
• AI Summarization - Automatic summaries for commits, PRs, and logs
• Log Analysis - Parse and analyze structured logs with filtering
• Documentation Generation - Auto-generate docs from Git history
• Key Points Extraction - Extract important insights from text
• RESTful API - FastAPI backend with automatic OpenAPI docs

Architecture

Watchtower is a monorepo with the following structure:

watchtower/
├── apps/
│   ├── backend/        # Python FastAPI backend
│   ├── cli/            # TypeScript CLI tool
│   └── web/            # Next.js web interface (coming soon)
├── packages/           # Shared packages and utilities
├── infra/              # Docker Compose and deployment configs
└── scripts/            # Build and automation scripts

Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 18+ (for CLI)
• Python 3.10+ (for backend development)
• Git

Start with Docker Compose

# Start backend and Qdrant
cd infra
docker compose up backend qdrant

# Backend: http://localhost:8000
# API docs: http://localhost:8000/docs
# Qdrant: http://localhost:6333

CLI Usage

# Install CLI dependencies
cd apps/cli
npm install
npm run build

# Watch a repository
npm start watch ./my-project

# Generate documentation
npm start docs ./CHANGELOG.md

# View all commands
npm start help

Key Components

Backend

Python FastAPI backend with vector search, AI summarization, and log analysis.

Key Features:

• Vector storage (Qdrant + SQLite fallback)
• OpenAI embeddings + deterministic fallback
• Log parsing (ISO8601, bracketed, plain text)
• Text summarization with extractive fallback
• Key points extraction

API Endpoints:

• POST /summarize - Summarize text
• POST /embed - Generate embeddings
• POST /index - Index documents
• POST /search - Semantic search
• GET /documents - List indexed documents
• POST /logs/parse - Parse and analyze logs
• POST /analyze/keypoints - Extract key points

See apps/backend/README.md for details.

CLI

TypeScript command-line tool for file watching, Git integration, and documentation generation.

Commands:

• watch <repo> - Monitor repository changes
• commits [count] - List recent commits
• pr <number> - Summarize pull request
• docs [output] - Generate documentation
• bulk <repo> - Bulk index repository
• summary <source> - Summarize text or file

See apps/cli/README.md for details.

Configuration

Backend Environment Variables

Variable	Default	Description
VECTOR_DB_PATH	./vector_store.db	SQLite database path
QDRANT_URL	-	Qdrant server URL
QDRANT_API_KEY	-	Optional Qdrant API key
OPENAI_API_KEY	-	OpenAI API key
OPENAI_MODEL	gpt-3.5-turbo	OpenAI model
VECTOR_DIM	1536	Embedding dimension

CLI Environment Variables

Variable	Default	Description
WATCHTOWER_BACKEND_URL	http://localhost:8000	Backend URL
BACKEND_URL	http://localhost:8000	Alternative backend URL

Development

Backend Development

cd apps/backend

# Create virtualenv
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run with live reload
uvicorn app.main:app --reload

# Run tests
PYTHONPATH=. pytest -v

CLI Development

cd apps/cli

# Install dependencies
npm install

# Run in dev mode
npm run dev watch ./my-project

# Build TypeScript
npm run build

# Run built version
npm start watch ./my-project

Testing

Backend Tests

cd apps/backend
PYTHONPATH=. pytest -v

# With coverage
PYTHONPATH=. pytest --cov=app tests/

Tests include:

• Vector search and indexing (3 tests)
• Log parsing and summarization (8 tests)

Integration Testing

# Start services
cd infra
docker compose up backend qdrant

# Index sample content
curl -X POST http://localhost:8000/index \
  -H 'Content-Type: application/json' \
  -d '{"texts":["Python is great"],"sources":["doc1.txt"]}'

# Search
curl -X POST http://localhost:8000/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"programming","top_k":5}'

Use Cases

Auto-Documentation

# Watch repo and generate docs periodically
watchtower watch ./my-project &
watchtower docs ./docs/CHANGELOG.md

Log Analysis

# Parse logs from file
watchtower summary ./app.log

# Or via API
curl -X POST http://localhost:8000/logs/parse \
  -H 'Content-Type: application/json' \
  -d '{"text":"2026-01-12T10:30:45Z ERROR Connection failed"}'

Code Search

# Index entire repository
watchtower bulk ./my-project

# Search via API
curl -X POST http://localhost:8000/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"authentication implementation","top_k":5}'

Docker Services

The project includes Docker Compose configuration for:

• backend - FastAPI application with uvicorn --reload
• qdrant - Vector database (optional, falls back to SQLite)
• web - Next.js web interface (coming soon)

# Start all services
docker compose up

# Start specific services
docker compose up backend qdrant

# View logs
docker compose logs -f backend

Roadmap

Phase 1 (MVP) ✅

• CLI file watcher
• Vector search and indexing
• AI summarization
• Log parsing
• Git integration
• Documentation generation

Phase 2 (In Progress)

• Web UI with Next.js
• Timeline view of changes
• Advanced search filters
• GitHub/GitLab CI integration
• Slack notifications

Phase 3 (Planned)

• Multi-project aggregation
• Team dashboards
• Predictive insights
• Anomaly detection
• Collaboration features

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

License

See LICENSE file for details.

Support

• Documentation: See component READMEs
• Issues: GitHub Issues
• API Docs: http://localhost:8000/docs (when running)