GrantFlow

Version: 0.1.0 · Last updated: 2026-09-15

GrantFlow is an open-source platform for budget management and financial reporting in NGOs and donor organizations. It was born from 20 years of watching organizations manage grant budgets in incompatible Excel files — and a belief that modern software engineering can fix that.

Status: Active development — live in production.

→ Product Overview — what GrantFlow does, who it's for, and why it exists.

Architecture

graph TB
    FE["Frontend\nReact 19 + Vite\n:5173 (dev)"]
    GW["Nginx Gateway\n:8082"]

    FE -->|HTTP| GW

    GW -->|/api/v1/users, /auth,\n/register, /customers, …| US
    GW -->|/api/v1/budgets, /budget-lines,\n/reports, /attachments, …| BS
    GW -->|/api/v1/ai| AI
    GW -->|/api/v1/chat\nSSE streaming| CH

    subgraph Services
        US["users-service\nFastAPI :8000"]
        BS["budget-service\nFastAPI :8001"]
        AI["ai-service\nFastAPI :8002\n(stateless reasoning)"]
        CH["chat-service\nFastAPI :8003\n(agent host)"]
        WK["worker\nCelery"]
    end

    CH -->|POST /ai/decide\nplain JSON| AI
    CH -->|REST\ntool dispatch| BS

    subgraph Data
        PG[("PostgreSQL :5432\ngrandflow_users\ngrandflow_budget\ngrandflow_ai\ngrandflow_chat")]
        RD[("Redis :6379\nSessions · Rate limits")]
        RMQ[("RabbitMQ :5672\nEvent broker / Celery transport")]
    end

    subgraph Observability
        OC["OTEL Collector\n:4317"]
        JG["Jaeger\n:16686"]
        PM["Prometheus\n:9090"]
        GF["Grafana\n:3002"]
    end

    US --> PG
    BS --> PG
    AI --> PG
    CH --> PG
    AI --> RD
    US --> RMQ
    BS -->|consumes events| RMQ
    WK -->|broker| RMQ
    WK -->|result backend| RD
    US -->|OTLP| OC
    BS -->|OTLP| OC
    AI -->|OTLP| OC
    CH -->|OTLP| OC
    OC --> JG
    OC --> PM
    PM --> GF

Communication patterns:

Frontend → Services: via Nginx (single entry point at :8082), including a direct route to ai-service (/api/v1/ai/*) for account-level settings/model catalog, separate from chat-service's own decision-request path
chat-service → ai-service: direct HTTP, stateless decision requests (POST /ai/decide) via shared/ai_client
chat-service → budget-service: direct HTTP, curated tool dispatch (MCP-shaped registry; resource ids injected server-side, never supplied by the model)
budget-service → users-service: direct HTTP (service discovery via env var)
users-service → budget-service: RabbitMQ events (user created/updated)
chat-service streams responses to the frontend via Server-Sent Events (SSE)
Dependency DAG is acyclic by design: frontend → chat, chat → ai, chat → domain REST. No ai → domain, no domain → domain, no domain → ai — ai carries zero domain knowledge and every domain service can, in principle, be rewritten in another stack independently.

Tech Stack

Layer	Technology
Backend	Python 3.11+ · FastAPI 0.116 · Pydantic v2
Frontend	React 19 · TypeScript 5.8 · Vite · TailwindCSS · TanStack Query
ORM	SQLAlchemy 2.0 (async) · Alembic migrations
Database	PostgreSQL 15 (one DB per service)
Cache	Redis 7
Messaging	RabbitMQ 3 (aio-pika)
Auth	JWT (HS256) · refresh token rotation via Redis
AI	Anthropic API (BYOK) · Ollama (local dev) · pydantic-ai
Email	MailerSend · Mailjet (transactional, dual-provider)
Observability	OpenTelemetry (OTLP) · Jaeger/Prometheus/Grafana (dev) · Grafana Cloud (prod)
Gateway	Nginx
Containerization	Docker · Docker Compose
CI	GitHub Actions (lint + tests per service)

Services

users-service `:8000`

User and customer management, JWT authentication, role-based access control. Publishes user.created / user.updated events to RabbitMQ. Customers are modelled with is_ngo and is_donor boolean flags to support both sides of a grant relationship.

budget-service `:8001`

Budget and budget-line CRUD. Consumes user events from RabbitMQ to maintain a local read model. Carries zero AI/chat knowledge — the parse-to-budget flow is driven by chat-service against this service's public REST API. Key endpoints:

POST /api/v1/budgets/with-lines — atomic create: budget + all lines in one transaction
Donor template mapping: detects and maps Excel donor budget formats to a normalized schema

ai-service `:8002`

Pure stateless reasoning — no domain knowledge, no outbound calls to other services. POST /ai/decide takes a message, conversation history, tool JSON schemas, and domain context, and returns either a tool-call decision or a reply. Features:

Provider abstraction: Ollama (dev) → Anthropic (prod, BYOK), switchable per-customer
Per-customer rate limiting via Redis (default: 100 req/hour)
Full audit log of every AI request (model, tokens, duration, success/failure)
Prompt versioning: system and user prompts stored in DB, swappable without deploys

chat-service `:8003`

Agent host — owns conversations and messages server-side (any-device chat history), the tool registry, and the dispatch loop. Serves POST /chat/stream (SSE) to the frontend and calls ai-service's /ai/decide for reasoning via shared/ai_client. Features:

MCP-shaped tool registry (list_tools() / call_tool()): the budget toolset is generated by an in-process FastMCP from_openapi bridge over budget's OpenAPI spec (mcp_bridge.py), with route maps and a dispatch bridge for server-injected resource ids
Deterministic guards in code: targeted tools require page context; resource ids (e.g. budget_id) are injected server-side from the URL context, never supplied by the model
Parse-text-to-budget flow: consumes ai-service's parse stream, creates via budget's public REST, re-emits progress events to the frontend

worker (Celery)

Background jobs shared across services — RabbitMQ as broker, Redis as result backend, per-domain queues (ai, budget, users). Runs a daily scheduled cleanup of expired AI sessions, plus on-demand tasks: verification/invite/password-reset email delivery and feedback notifications.

Key Design Decisions

Decision	Rationale
One PostgreSQL DB per service	Enforces service boundaries; avoids shared-schema coupling
Shared Python library (`/shared`)	Common JWT logic, Pydantic schemas, OpenTelemetry setup, and the `ai_client` decision-request library without duplication
RabbitMQ over direct HTTP for user events	Decouples budget-service from users-service availability
OpenTelemetry (OTLP) over Sentry	Vendor-agnostic; same instrumentation works with Jaeger today, any backend tomorrow
FastAPI async-first	All I/O (DB, Redis, HTTP, RabbitMQ) runs async; no sync blocking in the hot path
Nginx as single gateway	One CORS policy, one entry point; services are not directly exposed
Dedicated chat-service (agent host) over client-held history or ai-owned threads	Any-device chat history needs a server; keeps ai-service stateless and domain services free of chat plumbing
ai-service is pure stateless reasoning (`/ai/decide`), no outbound calls	Keeps the dependency DAG acyclic (`frontend → chat → {ai, domain REST}`); domain services stay swappable for another stack independently
Tool registry is MCP-shaped from day one	Same consumer-facing interface for hand-curated and OpenAPI→MCP-bridged tools; budget's registry now runs entirely on the OpenAPI→MCP bridge

Observability

All services export traces and metrics via OTLP to the OpenTelemetry Collector, which fans out to Jaeger (traces) and Prometheus (metrics). Grafana sits on top of Prometheus for dashboards.

Auto-instrumented via shared/observability/__init__.py:

FastAPI request/response spans
SQLAlchemy query spans
Redis command spans (ai-service)

Tool	URL	Purpose
Jaeger	http://localhost:16686	Distributed traces, latency, error rates
Prometheus	http://localhost:9090	Metrics queries and scrape targets
Grafana	http://localhost:3002	Dashboards (admin / admin)
RabbitMQ UI	http://localhost:15672	Queue inspection, message rates

For more detail see monitoring/README.md.

Running Locally

Two modes are available depending on the use case:

	Dev mode	Local mode
Use case	Active development	Demo, testing, non-technical users
Services	Run on host (hot reload)	Run in Docker (no local deps needed)
Entry point	`./dev.sh`	`./local.sh`
Frontend	http://localhost:5173	http://localhost:4000
Nginx gateway	http://localhost:8082	http://localhost:9082

Dev mode

Prerequisites: Docker, Python 3.11+, Node.js 18+

Infrastructure runs in Docker; services run on the host for hot reload.

# 1. Start infrastructure (PostgreSQL, Redis, RabbitMQ, Nginx, observability)
./dev.sh up

# 2. Start each service in its own terminal
cd services/users  && alembic upgrade head && python -m uvicorn main:app --reload --port 8000
cd services/budget && alembic upgrade head && python -m uvicorn main:app --reload --port 8001
cd services/ai     && alembic upgrade head && python -m uvicorn main:app --reload --port 8002
cd services/chat   && alembic upgrade head && python -m uvicorn main:app --reload --port 8003

# 3. Start the frontend
cd frontend-typescript && npm install && npm run dev

Dev mode endpoints:

	URL
Frontend	http://localhost:5173
Nginx gateway	http://localhost:8082
Users API docs	http://localhost:8000/docs
Budget API docs	http://localhost:8001/docs
AI API docs	http://localhost:8002/docs
Chat API docs	http://localhost:8003/docs

VSCode debugging — each service exposes debugpy (enable with VSCODE_DEBUGGER=1):

Service	debugpy port
users-service	5678
budget-service	5680
ai-service	5682
chat-service	5684

Attach from VS Code with "remoteRoot": "/app".

Other dev.sh commands:

./dev.sh down     # Stop infrastructure
./dev.sh logs     # Stream container logs
./dev.sh status   # Show container status
./dev.sh rebuild  # Rebuild images without cache
./dev.sh clean    # Stop and remove volumes

Local mode

Prerequisites: Docker only

Everything runs in Docker — intended for demos, integration testing, or sharing with non-technical users.

./local.sh up

Local mode endpoints:

	URL
Frontend	http://localhost:4000
Nginx gateway	http://localhost:9082
Users service	http://localhost:9020
Budget service	http://localhost:9021

Other local.sh commands:

./local.sh down            # Stop all services
./local.sh logs [SERVICE]  # Stream logs (optionally for one service)
./local.sh status          # Show container status
./local.sh rebuild         # Rebuild images without cache
./local.sh clean           # Stop and remove volumes
./local.sh shell [SERVICE] # Open a shell in a container (default: users)

Running e2e tests locally

The Playwright suite (frontend-typescript/e2e/) covers the auth + budget CRUD journey — both at the API layer (api project, no browser) and through the real browser UI (browser project, chromium) — against the local-mode stack:

./local.sh up
# once containers are healthy:
npx playwright test --config=frontend-typescript/e2e/playwright.config.ts

Scope is deliberately narrow for this first suite: auth + budget CRUD only. AI chat and donor-dashboard/donor-grantee-relationship flows are excluded for now — a fast-follow, not a technical blocker; see frontend-typescript/e2e/README.md and openspec/changes/e2e-test-suite/ for the full rationale and local-run details (cleanup convention, local vs dev port notes).

Project Structure

GrantFlow/
├── .github/workflows/      # CI: lint + tests per service
├── docker/                 # Postgres init (creates 4 DBs)
├── docker-compose.dev.yml  # Infrastructure-only compose (dev mode)
├── docker-compose.local.yml # Full containerized compose (local mode)
├── docker-compose.prod.yml  # Production compose (Hetzner deploy)
├── dev.sh                  # Dev mode entry point
├── local.sh                # Local mode entry point
├── frontend-typescript/    # React + Vite + TypeScript app
├── monitoring/             # OTEL collector, Prometheus, Grafana configs
├── nginx/                  # Gateway config (dev + prod)
├── scripts/                # Utility scripts (issue creation, etc.)
├── shared/                 # Shared Python library
│   ├── ai_client/          # In-process client for ai-service's /ai/decide (retries, timeouts, decision parsing)
│   ├── db/                 # Audit mixin, custom column types
│   ├── exceptions/         # Shared exception types
│   ├── observability/      # OpenTelemetry setup
│   ├── schemas/            # Pydantic schemas (cross-service)
│   ├── security/           # JWT utils, FastAPI auth dependencies
│   ├── services/           # Currency service, transactional email (MailerSend/Mailjet)
│   ├── storage/            # S3-compatible storage service (report attachments)
│   └── utils/              # HTTP client wrapper
├── services/
│   ├── users/              # FastAPI: users, customers, auth
│   ├── budget/             # FastAPI: budgets, budget lines
│   ├── ai/                 # FastAPI: stateless LLM reasoning (/ai/decide), rate limiting, audit logs
│   ├── chat/               # FastAPI: agent host — conversations, tool registry, dispatch loop, SSE streaming
│   └── worker/             # Celery: background jobs (RabbitMQ broker, Redis result backend)
└── terraform/              # Prod infra provisioning (Hetzner Cloud)

Each service follows the same internal layout:

service/
├── app/
│   ├── api/          # Route handlers
│   ├── crud/         # DB operations
│   ├── models/       # SQLAlchemy ORM models
│   ├── schemas/      # Pydantic request/response
│   ├── services/     # Business logic
│   └── core/         # Config, logging, exceptions
├── migrations/       # Alembic versions
├── tests/
└── main.py

CI/CD

GitHub Actions runs on every push/PR touching a service or shared/:

Workflow	Triggers	Steps
`users.yml`	`services/users/`, `shared/`	black · mypy · flake8
`budget.yml`	`services/budget/`, `shared/`	pytest · black · mypy · flake8
`ai.yml`	`services/ai/`, `shared/`	pytest · black · mypy · flake8
`chat.yml`	`services/chat/`, `shared/`	pytest · black · mypy · flake8
`worker.yml`	`services/worker/**`	black · flake8 · pytest
`shared.yml`	`shared/**`	black · flake8 · pytest (`shared/ai_client`, `shared/tests`)
`frontend.yml`	`frontend-typescript/**`	vitest (with coverage)
`compose.yml`	compose files, `.env*` (changed paths)	Docker Compose Validation — config lint
`e2e.yml`	`services/users/`, `services/budget/`, `shared/`, `frontend-typescript/` (also `workflow_dispatch`)	Boots the local-mode stack · Playwright `api` + `browser` projects · teardown
`deploy.yml`	push to `main`	Deploy to VPS over SSH (`workflow_dispatch` also)

Contributing

Fork the repo and create a branch: git checkout -b feature/your-feature
Run the relevant service tests: cd services/<service> && pytest
Run linters: black . && mypy . && flake8
Open a pull request

License

GNU AGPL v3 — see LICENSE.

Name		Name	Last commit message	Last commit date
.agents/skills		.agents/skills
.claude		.claude
.github		.github
.vscode		.vscode
docker/postgres		docker/postgres
docs		docs
frontend-typescript		frontend-typescript
monitoring		monitoring
nginx		nginx
openspec		openspec
scripts		scripts
services		services
shared		shared
terraform		terraform
uploads/budget		uploads/budget
.dockerignore		.dockerignore
.env.dev		.env.dev
.env.local		.env.local
.env.prod		.env.prod
.flake8		.flake8
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Caddyfile		Caddyfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
cloud.sh		cloud.sh
dev.sh		dev.sh
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.local.yml		docker-compose.local.yml
docker-compose.prod.yml		docker-compose.prod.yml
local.sh		local.sh
mypy.ini		mypy.ini
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
sanity_check.bat		sanity_check.bat
sanity_check.py		sanity_check.py
sanity_check.sh		sanity_check.sh

Navigation Menu

Uh oh!

Repository files navigation

GrantFlow

Architecture

Tech Stack

Services

users-service `:8000`

budget-service `:8001`

ai-service `:8002`

chat-service `:8003`

worker (Celery)

Key Design Decisions

Observability

Running Locally

Dev mode

Local mode

Running e2e tests locally

Project Structure

CI/CD

Contributing

License

About

Releases

Sponsor this project

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

GrantFlow

Architecture

Tech Stack

Services

users-service :8000

budget-service :8001

ai-service :8002

chat-service :8003

worker (Celery)

Key Design Decisions

Observability

Running Locally

Dev mode

Local mode

Running e2e tests locally

Project Structure

CI/CD

Contributing

License

About

Resources

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Contributors

Languages

users-service `:8000`

budget-service `:8001`

ai-service `:8002`

chat-service `:8003`