AI-powered advisory system for UN human rights officers. Uses RAG (Retrieval-Augmented Generation) over UN Human Rights Index (UHRI) documents with multi-agent orchestration powered by LangChain and LangGraph.
| Resource | URL |
|---|---|
| Application | https://hras.owenadirah.com |
| API | https://hras-api.owenadirah.com |
| API Documentation | https://hras-api.owenadirah.com/docs |
| Health Check | https://hras-api.owenadirah.com/health |
| Repository | https://github.com/owezzy/HRAS |
- Access the Application: Visit https://hras.owenadirah.com
- Start a Conversation: Navigate to the Chat interface
- Ask Questions: Type natural language questions about UN human rights recommendations
- View Sources: Each response includes citations from UHRI documents
| Step | Action | Documentation |
|---|---|---|
| 1 | Read this README | Understand project overview and architecture |
| 2 | Review Docs Index | Navigate all documentation |
| 3 | Set up local environment | Follow Quick Start below |
| 4 | Explore Backend | Backend README - API, testing, agents |
| 5 | Explore Frontend | Frontend README - UI, components, styling |
| 6 | Understand Deployment | Cloudflare Deployment - production setup |
| Task | Documentation |
|---|---|
| Deploy | npm run deploy in backend/cloudflare and frontend (guide) |
| Configure Secrets | npx wrangler secret put <NAME> per service |
| Troubleshoot Issues | Troubleshooting Guide |
HRAS enables human rights officers to ask natural language questions about UN human rights recommendations and receive AI-generated responses with source citations from UHRI documents.
Key Features:
- Conversational AI interface for querying UN human rights data
- RAG pipeline with semantic search across UHRI documents
- Multi-agent system for retrieval, generation, and validation
- Source attribution for every response
- Production deployment on Cloudflare Workers and Containers
| Component | Technology |
|---|---|
| Frontend | Next.js 15, React 19, MUI 7, TailwindCSS 4 |
| Backend | Python 3.12+, FastAPI, LangChain, LangGraph |
| AI/LLM | DeepSeek (deepseek-flash) via an OpenAI-compatible API |
| Embeddings | Cloudflare Workers AI (@cf/baai/bge-small-en-v1.5) |
| Vector Store | ChromaDB |
| Database | PostgreSQL (production) / SQLite (development) |
| Monitoring | LangSmith tracing |
| Hosting | Cloudflare Workers (frontend) + Containers (backend), deployed with Wrangler |
# Clone repository
git clone https://github.com/owezzy/HRAS.git
cd HRAS
# Install dependencies
make install
# Set up Ollama
ollama serve # Terminal 1
ollama login # Required for cloud models
ollama pull nomic-embed-text # Embedding model
# Configure environment
cp backend/.env.example backend/.env
# Edit backend/.env if needed
# Run development servers
make dev # Starts frontend + backend
# Frontend: http://localhost:3000
# Backend: http://localhost:8000# Ingest UHRI sample data (do this once)
make ingest
# Verify ingestion
make db-stats| Service | Host | Notes |
|---|---|---|
| Frontend | https://hras.owenadirah.com | Next.js standalone (Dockerfile.multi-stage), TLS via Let's Encrypt |
| Backend | https://hras-api.owenadirah.com | FastAPI (Dockerfile), ChromaDB on a persistent volume |
Backend providers: DeepSeek (deepseek-flash) for chat, Cloudflare Workers AI
(@cf/baai/bge-small-en-v1.5) for embeddings, LangSmith for tracing.
Both services build from this repository on push to main.
| Service | Root Directory | Dockerfile |
|---|---|---|
| Frontend | frontend |
Dockerfile.multi-stage |
| Backend | backend |
Dockerfile |
Required service variables:
| Variable | Service | Description |
|---|---|---|
LLM_API_KEY |
backend | DeepSeek API key |
EMBEDDING_BASE_URL |
backend | Host serving the embedding model |
EMBEDDING_API_KEY |
backend | Key for that host |
AUTH_SECRET |
frontend | NextAuth session secret |
There is no deploy-on-push. Deploy each service with Wrangler:
cd backend/cloudflare && npm ci && npm run deploy # needs Docker running
cd frontend && npm ci && npm run deploySee the Cloudflare Deployment guide.
- Cloudflare: Workers Paid plan plus Container usage
- LLM inference: pay-per-token (DeepSeek)
- Embeddings: pay-per-token (Cloudflare Workers AI)
- Stale
zarf/,nginx/, anddocs/deployment/aws/directories remain for reference only and are not part of the current deployment path.
Copy backend/.env.example to backend/.env and configure:
# Application
APP_ENV=development
DEBUG=true
# Database (SQLite for dev, PostgreSQL for production)
DATABASE_URL=sqlite+aiosqlite:///./hras.db
# Chat LLM (OpenAI-compatible: deepseek | openai | openrouter | ollama | custom)
LLM_PROVIDER=deepseek
LLM_API_KEY=
LLM_MODEL=deepseek-flash
# Embeddings (configured independently of chat)
EMBEDDING_BASE_URL=
EMBEDDING_API_KEY=
EMBEDDING_MODEL=@cf/baai/bge-small-en-v1.5
# Vector Store
CHROMA_PERSIST_DIRECTORY=./chroma_db
# CORS Origins (include frontend URL)
CORS_ORIGINS=["http://localhost:3000"]
# Feature Flags
USE_POSTGRES=false
USE_ASYNC_TOOLS=trueCreate frontend/.env for local development:
# API URL
NEXT_PUBLIC_API_URL=http://localhost:8000
# Base URL
NEXT_PUBLIC_BASE_URL=http://localhost:3000
# Auth Configuration
AUTH_URL=http://localhost:3000
AUTH_SECRET=your-secret-here # Generate with: openssl rand -base64 32
# Optional: OAuth Providers
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=Production variables are vars in each wrangler.jsonc; secrets are set with npx wrangler secret put.
| Category | Key Documents |
|---|---|
| Development | Backend README · Frontend README · Dev Guide |
| Deployment | Deployment Guide · Backend README |
| Architecture | System Architecture · AI/ML Pipeline |
| Reference | API Documentation · Evaluation · Docs Index · Troubleshooting |
# Development
make dev # Run frontend + backend
make frontend-dev # Frontend only (port 3000)
make backend-dev # Backend only (port 8000)
make install # Install all dependencies
make lint # Run linters
make test # Run tests
make format # Format code
# Data Management
make ingest # Ingest UHRI sample data
make ingest-clear # Clear and re-ingest
make db-stats # Show vector store stats
# Docker (for Kind local Kubernetes)
make kind-create # Create local K8s cluster
make kind-deploy # Deploy to Kind
make kind-status # Check deployment
make kind-clean # Remove cluster
# Utilities
make clean # Clean build artifacts
make build # Build frontend for productionSee make help for full command list.
HRAS/
├── frontend/ # Next.js 15 application
│ ├── src/
│ │ ├── app/ # App router pages
│ │ ├── @fuse/ # Fuse React UI components
│ │ └── components/ # HRAS components
│ ├── .env.production # Production environment
│ └── README.md # Frontend docs
├── backend/ # FastAPI application
│ ├── src/app/ # Main application
│ │ ├── api/ # API routes
│ │ ├── core/ # Config, dependencies
│ │ ├── schemas/ # Pydantic models
│ │ ├── services/ # Business logic
│ │ └── ai/ # AI/ML components
│ │ ├── agents/ # LangGraph multi-agent system
│ │ ├── chains/ # LangChain LCEL chains
│ │ ├── tools/ # Agent tools (UHRI client)
│ │ ├── vectorstore/ # ChromaDB management
│ │ └── prompts/ # Prompt templates
│ ├── tests/ # Pytest suite
│ ├── .env.example # Environment template
│ └── README.md # Backend docs
├── docs/ # Documentation
│ ├── 00-INDEX.md # Quick navigation
│ ├── architecture/ # System design docs
│ ├── deployment/ # Deployment guides
│ ├── development/ # Developer guides
│ ├── operations/ # Operations docs
│ └── reference/ # API reference
├── zarf/ # Legacy deployment configs (not in the deploy path)
│ ├── docker/ # Dockerfiles & Docker Compose
│ │ ├── compose/ # Docker Compose configurations
│ │ ├── caddy/ # Caddy reverse proxy config
│ │ └── monitoring/ # Loki, Promtail configs
│ ├── monitoring/ # Prometheus, Grafana configs
│ ├── k8s/ # Kubernetes manifests
│ └── scripts/ # Deployment scripts
├── .github/workflows/ # CI/CD pipeline
│ └── deploy-production-docker.yml
├── Makefile # Common tasks
└── README.md # This file
- Check Troubleshooting Guide for common issues
- Review API Documentation for endpoint details
- See Development Guide for setup help
- Open a GitHub issue for bugs or feature requests
MIT License - See LICENSE file for details