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

This is the beginning of the README. Read the rest at the original. Read the full README ↗