Skip to content

Developer Guide

Welcome to the Carbon Connect Developer Guide. This documentation covers everything you need to build, test, deploy, and extend the Carbon Funding Navigator platform.

Carbon Connect is a SaaS platform that matches SMEs with relevant EU and national carbon/sustainability grant opportunities. The system uses AI-powered matching algorithms with a focus on decarbonization funding, scrapes grant databases, processes eligibility criteria including carbon requirements, and provides intelligent recommendations with application assistance.

Quick Navigation

  • Getting Started

    Prerequisites, installation steps, first-time setup for backend and frontend, running the API server and Celery workers.

    Local Setup

  • Environment Variables

    Complete reference for all configuration variables grouped by service: database, cache, search, AI/LLM, carbon, auth, email, and AWS.

    Environment Reference

  • Docker Services

    Docker Compose services for PostgreSQL, Valkey, and Meilisearch. Dev profile tools, health checks, volume management, and troubleshooting.

    Docker Services

  • Architecture

    System architecture overview, data flow diagrams, the carbon-enhanced matching algorithm, and service interaction patterns.

    System Overview

  • Tech Stack

    Complete technology inventory with version numbers covering backend, frontend, AI/ML, infrastructure, and DevOps tooling.

    Tech Stack

  • Database Schema

    All tables, columns, relationships, carbon-specific fields, pgvector indexes, and Alembic migration commands.

    Database Schema

  • Multi-Tenancy

    Pool model with PostgreSQL Row-Level Security, tenant middleware implementation, S3 prefix isolation, and cross-tenant prevention.

    Multi-Tenancy

  • API Reference

    Full REST API documentation covering authentication, companies, grants, matches, applications, dashboard, partners, and reference data.

    API Reference

  • Core Services

    In-depth documentation for the matching engine, carbon services, data pipeline, search, notifications, storage, and background jobs.

    Core Services

  • Frontend

    Next.js 14 application architecture, component library, state management with React Query, and routing patterns.

    Frontend

  • Testing

    Testing philosophy, patterns for async tests, mocking strategies for external APIs, and coverage targets.

    Testing

  • Infrastructure

    AWS architecture, Terraform modules, CI/CD pipelines with GitHub Actions, and deployment procedures.

    Infrastructure

  • Contributing

    Code style guidelines, TDD requirements, PR process with the TDD Gate, and pre-commit hook setup.

    Contributing

At a Glance

Metric Value
Backend Tests 533 passing (pytest)
API Endpoints 40+ RESTful endpoints
Frontend Components 40+ React components
Grant Data Sources 4 active (CORDIS, EU Portal, Cohesion, Innovate UK)
Matching Algorithm 5-component hybrid scoring (semantic, rules, carbon, collaborative, recency)
Embedding Dimensions 768 (all-mpnet-base-v2)
Search Latency Sub-100ms (Meilisearch)

Key Principles

Test-Driven Development
TDD is non-negotiable. Every requirement must be captured as an automated test before writing production code. The PR template is wired to the PR TDD Gate GitHub Action, so missing evidence blocks merge automatically.
Async-First Architecture
All database operations and external API calls use async/await. The entire backend is built around Python's asyncio for maximum concurrency.
Multi-Tenant Isolation
All tenant-scoped data is isolated via PostgreSQL Row-Level Security policies. Every authenticated request validates tenant context through middleware.
Carbon-Centric Design
The matching engine, database schema, and UI are all optimized for carbon funding -- 25% of the matching score comes from carbon alignment analysis.