FiApply - AI Job & Scholarship Application Automation

FiApply automates job and scholarship applications using AI-powered browser automation, intelligent resume tailoring, and essay generation.

🏗️ Architecture

Monorepo Structure:

FiApply/
├── backend/        # Python gRPC microservices
├── frontend/       # React TypeScript PWA
├── proto/          # Protocol Buffer definitions
├── db/             # PostgreSQL database
└── docs/           # Documentation

Services:

1. API Gateway (50051) - Client-facing gRPC/HTTP endpoint
2. AI Orchestrator (50052) - Browser automation + AI workflows
3. RAG Engine (50053) - Vector search + document storage
4. LLM Manager (50054) - Ollama (local) + OpenRouter (cloud)

Tech Stack:

• Backend: Python 3.11+, gRPC, Connect RPC, Playwright, LangChain, LangGraph
• Frontend: React 18, TypeScript, Vite, ShadCN UI, Redux Toolkit, Connect-Web
• Database: PostgreSQL 17-alpine3.22 with pgvector, pg_trgm, pg_stat_statements
• AI: Stagehand (browser automation), Ollama/OpenRouter (LLMs)

---

🚀 Quick Start (Docker)

Fastest way to run the entire stack:

# Clone and enter repo  
git clone https://github.com/Firelight-Innovations/FiApply.git
cd FiApply

# Complete setup: install + build + start
make quickstart

# Or step by step:
./scripts/setup-env-modular.sh    # Set up environment variables
make build-fast                   # Build with BuildKit (fast!)
make up                           # Start all services

For active development (hot reload):

make watch
# Edit code → see changes in <5 seconds!

Access the application:

• 🎨 Frontend: http://localhost:5173
• 📚 Swagger API Docs: http://localhost:8080
• 🔧 gRPC Testing UI: http://localhost:8081
• 💾 PGAdmin: http://localhost:5050

See Docker.md for complete Docker documentation.

---

⚙️ Local Development Setup

Prerequisites

• Python 3.11+
• Node.js 18+
• Buf CLI - Installation
• uv (Python package manager) - Installation

Installation

1. Install Python Dependencies

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install all dependencies
uv pip install -r requirements.txt -r requirements-dev.txt

# Install Playwright browsers
playwright install chromium

2. Install Frontend Dependencies

cd frontend
npm install
cd ..

3. Generate Proto Code

# Generates Python, TypeScript, and OpenAPI specs
buf generate

This creates:

• Python gRPC stubs → backend/generated/
• TypeScript types → frontend/src/generated/
• OpenAPI specs → docs/openapi/

Proto Organization: Proto files are organized by domain in proto/ with service definitions, messages, and types separated for clarity. See proto/README.md for details.

4. Configure Environment

Quick Setup:

# Run the automated setup script
./scripts/setup-env.sh

Manual Setup:

# Create .env file from template
cp .env.example .env  # if it exists

Edit .env with your API keys:

# LLM Provider (Required)
OPENROUTER_API_KEY=sk-or-v1-your-key-here  # Get from https://openrouter.ai/keys

# Optional: Local LLM with Ollama
DEFAULT_PROVIDER=ollama  # Set to use local models
OLLAMA_URL=http://localhost:11434

# Optional: OpenAI for embeddings
OPENAI_API_KEY=sk-your-openai-key-here

# Development settings
BROWSER_HEADLESS=false  # See browser during automation
LOG_LEVEL=INFO

📖 For detailed configuration: Environment Setup Guide

---

🏃 Running Services

Option 1: Docker Compose (Recommended)

# Full stack with hot reload
make watch

# Full stack (all services)
make up

# Minimal dev setup (gateway + frontend + db)
make dev-minimal

# Individual services
make start-gateway
make start-frontend
make start-db

# View logs
make logs                # All services
make logs-gateway        # Specific service

# Stop all
make down

Option 2: Individual Services (Local)

Terminal 1 - LLM Manager:

python -m backend.services.llm_manager.server

Terminal 2 - RAG Engine:

python -m backend.services.rag_engine.server

Terminal 3 - AI Orchestrator:

python -m backend.services.ai_orchestrator.server

Terminal 4 - API Gateway:

python -m backend.api_gateway.server

Terminal 5 - Frontend:

cd frontend
npm run dev
# Runs on http://localhost:5173

---

🛠️ Development Workflow

Core Make Commands

make help          # Show all 40+ available commands
make quickstart    # Complete setup: install + build + start
make watch         # Enable hot reload (BEST for development!)
make dev-minimal   # Minimal dev setup (gateway + frontend + db)
make up            # Start all services
make down          # Stop all services
make build-fast    # Build with parallel + cache (5-10x faster)
make proto         # Generate code from proto files
make status        # Check service status
make health        # Check service health

Individual Service Control

# Start/stop/restart individual services
make start-gateway
make stop-gateway
make restart-gateway
make logs-gateway

# Service groups
make backend-up    # All backend services
make ai-dev       # AI development services
make rag-dev      # RAG development services

Build & Maintenance

make build-fast    # Fast parallel build
make rebuild-gateway  # Force rebuild specific service
make prune         # Clean unused images/volumes
make clean-cache   # Clean Docker build cache
make reset         # Complete reset

Development Tools

make swagger       # Open API documentation
make grpcui        # Open gRPC testing UI
make db            # Open database browser
make shell-gateway # Shell into service container

Code Generation

After modifying .proto files:

make proto
# or: buf generate

---

📚 Documentation

Document	Description
proto/README.md	Proto file organization and quick reference
Docker.md	Complete Docker guide with 40+ commands
frontend/README.md	Frontend architecture and setup
docs/context/Architecture.md	Full-stack architecture overview

---

🔧 Development Tools

All tools run automatically with Docker.

Core Services

Service	Port	Size	Description
api-gateway	50051	400MB	Client-facing gRPC/HTTP gateway
ai-orchestrator	50052	1.2GB	Browser automation + AI workflows
rag-engine	50053	700MB	Vector search + embeddings
llm-manager	50054	600MB	Ollama + OpenRouter integration
grpcwebproxy	9090	50MB	gRPC-Web to gRPC HTTP/2 proxy
frontend	5173	200MB	React TypeScript UI (Vite)

Support Services

Service	Port	Description
postgres	5432	PostgreSQL with pgvector
pgadmin	5050	Database management UI (optional)
ollama	11434	Local LLM runtime (optional)
swagger-ui	8080	API documentation
grpcui	8081	Interactive gRPC testing

Access via:

make swagger    # http://localhost:8080
make grpcui     # http://localhost:8081
make db         # http://localhost:5050 (pgAdmin)

---

🏗️ Project Structure

FiApply/
├── backend/
│   ├── api_gateway/
│   │   └── Dockerfile              # Gateway-specific (400MB)
│   ├── services/
│   │   ├── ai_orchestrator/
│   │   │   └── Dockerfile          # With Playwright (1.2GB)
│   │   ├── rag_engine/
│   │   │   └── Dockerfile          # Vector DB (700MB)
│   │   └── llm_manager/
│   │       └── Dockerfile          # AI/LLM (600MB)
│   └── shared/                     # Shared utilities
├── frontend/
│   ├── src/
│   │   ├── components/             # React components
│   │   ├── features/               # Feature modules
│   │   └── generated/              # Generated proto types
│   └── Dockerfile                  # Optimized (200MB)
├── proto/                          # Protocol Buffers (domain-organized)
│   ├── common/v1/                  # Shared error & metadata types
│   ├── gateway/v1/                 # API Gateway definitions
│   ├── ai/{orchestrator,llm,rag}/v1/  # AI service definitions
│   └── streaming/v1/               # Browser streaming protocol
├── db/
│   └── Dockerfile                  # Pre-built pgvector (200MB)
├── requirements-base.txt           # Core dependencies
├── requirements-ai.txt             # AI/LLM libraries
├── requirements-browser.txt        # Playwright
├── requirements-rag.txt            # Vector DB
├── docker-compose.yml              # Full stack
├── docker-compose.dev.yml          # Minimal dev setup
├── Makefile                        # 40+ commands
└── buf.gen.yaml                    # Proto generation

---

🧪 Testing the Setup

1. Health Check

# Via REST
curl http://localhost:50051/fiapply.gateway.v1.Gateway/HealthCheck \
  -H "Content-Type: application/json" \
  -d '{}'

# Via gRPC UI
make grpcui
# Navigate to http://localhost:8081

2. Frontend

# Visit http://localhost:5173
# Should see the health dashboard

3. API Documentation

make swagger
# Opens http://localhost:8080
# Try the HealthCheck endpoint

---

🚢 Deployment

Building for Production

# Build optimized Docker images
docker-compose -f docker-compose.yml build

# Frontend production build
cd frontend
npm run build
# Output in dist/

Environment Variables

Production deployment requires:

# Required
STAGEHAND_API_KEY=...
OPENROUTER_API_KEY=...

# Database
DB_HOST=postgres
DB_PORT=5432
DB_NAME=fiapply
DB_USER=fiapply_user
DB_PASSWORD=fiapply_password

# Service ports (optional)
GATEWAY_PORT=50051
AI_ORCHESTRATOR_PORT=50052
RAG_ENGINE_PORT=50053
LLM_MANAGER_PORT=50054

---

🔍 Troubleshooting

Docker Issues

# Clean restart
make reset
make build-fast
make up

# View logs
make logs-<service>

# Check service status
make status
make health

Hot Reload Not Working

# Restart watch mode
docker-compose down
make watch

Build Failures

make clean-cache
make rebuild-<service>

See Docker.md for complete troubleshooting guide.

---

🔗 Resources

• Buf
• Connect RPC
• Playwright
• Stagehand
• ShadCN UI
• LangChain
• Ollama

---

Built with ❤️ by Firelight Innovations