Architecture Overview

Rephole uses a producer-consumer architecture with separate services for optimal performance and scalability.

System Components

1. API Server (Producer)

• Purpose: Handle HTTP requests and enqueue background jobs
• Port: 3000
• Responsibilities:
  • Accept repository ingestion requests
  • Add jobs to BullMQ queue
  • Provide job status endpoints
  • Handle semantic search queries
  • Return results to clients
• Does NOT: Process repositories or perform heavy computations

2. Background Worker (Consumer)

• Purpose: Process repository ingestion jobs asynchronously
• Port: 3002
• Responsibilities:
  • Clone repositories
  • Parse code files (AST analysis)
  • Generate AI embeddings
  • Store vectors in ChromaDB
  • Update metadata in PostgreSQL
• Does NOT: Handle HTTP requests or API calls

3. Redis Queue (BullMQ)

• Purpose: Reliable job queue between API and Worker
• Features:
  • Job persistence
  • Automatic retries (3 attempts)
  • Exponential backoff
  • Job status tracking
  • Failed job management

4. Vector Database (ChromaDB)

• Purpose: Store and search code embeddings
• Features:
  • Fast semantic search
  • Similarity scoring
  • Metadata filtering

5. PostgreSQL

• Purpose: Store file content and metadata
• Data:
  • Repository state
  • File contents (full source code)
  • Processing metadata
  • Job history

Technology Stack

Category	Technology	Version
Backend Framework	NestJS	11.0
Job Queue	BullMQ	5.63
Vector Storage	ChromaDB	3.1
Database	PostgreSQL	15+
Cache/Queue	Redis	7+
AI/ML	OpenAI API	text-embedding-3-small
AST Parsing	Tree-sitter	Latest
Infrastructure	Docker & Docker Compose	Latest
Package Manager	pnpm	Latest

Why Producer-Consumer?

Benefits

1. Scalability: Scale API and workers independently
2. Reliability: Jobs persist in Redis; survive crashes
3. Performance: API responds immediately; heavy work is async
4. Observability: Track job progress and failures separately

Trade-offs

1. Complexity: More moving parts than monolithic
2. Latency: Results not immediate (polling required)
3. Infrastructure: Requires Redis for queue

Scaling Workers

Based on queue length:

docker-compose up --scale worker=5

Next Steps

• See Data Flow for detailed sequence diagrams
• Learn about Supported Languages