Tech Stack
Complete technology inventory for the Carbon Connect platform with version numbers, purposes, and package sources.
Backend
Core Framework
| Technology | Version | Package | Purpose |
| Python | 3.11+ | -- | Runtime language |
| FastAPI | ^0.128.0 | fastapi | Async REST API framework with automatic OpenAPI docs |
| Uvicorn | ^0.27.0 | uvicorn[standard] | ASGI server with hot-reload for development |
| Pydantic | ^2.6.0 | pydantic | Data validation and serialization |
| Pydantic Settings | ^2.2.1 | pydantic-settings | Environment variable management |
Database and ORM
| Technology | Version | Package | Purpose |
| PostgreSQL | 16 | Docker image | Primary relational database |
| SQLAlchemy | ^2.0.28 | sqlalchemy[asyncio] | Async ORM with declarative models |
| asyncpg | ^0.29.0 | asyncpg | Async PostgreSQL driver |
| Alembic | ^1.13.1 | alembic | Database migration management |
| pgvector | ^0.2.5 | pgvector | 768-dimensional vector storage and HNSW similarity search |
| psycopg2-binary | ^2.9.11 | psycopg2-binary (dev) | Sync PostgreSQL driver for migrations |
Cache and Message Queue
| Technology | Version | Package | Purpose |
| Valkey | 8 | Docker image | Redis-compatible in-memory cache and Celery broker |
| redis (Python client) | ^5.0.3 | redis | Python client for Valkey/Redis |
| Celery | ^5.3.6 | celery[redis] | Distributed task queue for background jobs |
| Flower | ^2.0.1 | flower | Celery monitoring dashboard |
Search
| Technology | Version | Package | Purpose |
| Meilisearch | 1.6 | Docker image | Sub-100ms full-text search engine |
| meilisearch-python-sdk | ^3.0.0 | meilisearch-python-sdk | Async Python client for Meilisearch |
Authentication and Security
| Technology | Version | Package | Purpose |
| PyJWT | ^2.10.1 | pyjwt | JWT token creation and verification |
| passlib | ^1.7.4 | passlib[bcrypt] | Password hashing (bcrypt) |
| bcrypt | <5.0.0 | bcrypt | Bcrypt algorithm (pinned for passlib compatibility) |
| python-multipart | ^0.0.20 | python-multipart | Form data parsing for file uploads |
| email-validator | ^2.3.0 | email-validator | Email address validation |
HTTP and Networking
| Technology | Version | Package | Purpose |
| httpx | ^0.27.0 | httpx | Async HTTP client for external API calls |
| aiosmtplib | ^3.0.2 | aiosmtplib | Async SMTP email delivery |
| sse-starlette | ^2.0.0 | sse-starlette | Server-Sent Events for streaming responses |
| aioboto3 | ^15.5.0 | aioboto3 | Async AWS SDK for S3 and Secrets Manager |
AI and Machine Learning
| Technology | Version | Package | Purpose |
| Anthropic Claude | ^0.40.0 | anthropic | LLM API client for application generation |
| sentence-transformers | ^2.6.1 | sentence-transformers | Embedding model (all-mpnet-base-v2) |
| PyTorch | >=2.8.0 | torch | Neural network runtime for embeddings |
| google-genai | ^1.0.0 | google-genai | Deprecated -- legacy Gemini client |
Utilities
| Technology | Version | Package | Purpose |
| tenacity | ^9.0.0 | tenacity | Retry logic with exponential backoff |
| structlog | ^25.5.0 | structlog | Structured logging |
| Jinja2 | ^3.1.4 | jinja2 | Email template rendering |
| python-dotenv | ^1.0.1 | python-dotenv | Environment variable loading from .env |
Frontend
Core Framework
| Technology | Version | Purpose |
| Next.js | 14+ | React framework with App Router, SSR, and API routes |
| React | 18+ | UI component library |
| TypeScript | ES2022+ (strict) | Type-safe JavaScript |
UI and Styling
| Technology | Purpose |
| Tailwind CSS | Utility-first CSS framework |
| shadcn/ui | Accessible component library built on Radix UI |
| Radix UI | Unstyled, accessible UI primitives |
State and Data
| Technology | Purpose |
| React Query (TanStack Query) | Server state management and caching |
| React Hook Form | Form state management and validation |
| Zod | Schema-based form validation |
| Technology | Purpose |
| ESLint | JavaScript/TypeScript linting |
| Prettier | Code formatting |
AI and Machine Learning
LLM Integration
| Model | Provider | Cost (Input/Output) | Use Case |
| Claude Sonnet 4 | Anthropic | $3 / $15 per 1M tokens | Application generation (default) |
| Claude Opus 4 | Anthropic | $15 / $75 per 1M tokens | Complex analysis and review |
| Claude Haiku 3.5 | Anthropic | $0.80 / $4 per 1M tokens | Quick classification and extraction |
Embeddings
| Model | Dimensions | Max Sequence Length | Purpose |
| all-mpnet-base-v2 | 768 | 384 tokens | Semantic similarity for grant matching |
Carbon Calculations
| Service | Provider | Purpose |
| Climatiq API | Climatiq | GHG Protocol-compliant emission factors (Scope ½/3) |
Infrastructure
AWS Services
| Service | Purpose |
| ECS Fargate | Container orchestration for API and workers |
| RDS PostgreSQL | Managed database with automated backups |
| ElastiCache (Valkey) | Managed cache and message broker |
| S3 | Document and file storage with lifecycle policies |
| CloudFront | CDN for static assets |
| ALB | Application Load Balancer with TLS termination |
| KMS | Encryption key management |
| Secrets Manager | Credential and API key storage |
| SES | Transactional email delivery |
| Lambda | Event-driven functions (< 66 req/sec workloads) |
| VPC | Network isolation with public/private/data subnets |
Infrastructure as Code
| Technology | Purpose |
| Terraform | AWS resource provisioning (VPC, RDS, ElastiCache, S3, ALB, ECS) |
| Docker | Application containerization |
| Docker Compose | Local development service orchestration |
DevOps and CI/CD
GitHub Actions Workflows
| Workflow | Trigger | Purpose |
| Backend CI | Push to main, all PRs | pytest with --maxfail=1, optional Ruff linting |
| PR TDD Gate | All PRs | Enforce TDD compliance (checklist validation) |
| Frontend CI | Push to main, all PRs | Frontend tests, linting, TypeScript compilation |
Code Quality
| Tool | Version | Purpose |
| Ruff | ^0.3.0 | Fast Python linter (replaces flake8, isort rules) |
| Black | ^24.3.0 | Python code formatter |
| isort | ^5.13.2 | Python import sorting |
| ESLint | -- | TypeScript/JavaScript linting |
| Prettier | -- | TypeScript/JavaScript formatting |
Testing
| Tool | Version | Purpose |
| pytest | ^8.1.0 | Python test runner |
| pytest-asyncio | ^1.3.0 | Async test support |
| pytest-cov | ^6.0.0 | Coverage reporting |
| Playwright | -- | E2E browser automation (planned) |
Pre-commit Hooks
| Hook | Purpose |
| check-added-large-files | Block files > 500KB |
| check-merge-conflict | Detect conflict markers |
| detect-private-key | Prevent private key commits |
| check-yaml | Validate YAML syntax |
| detect-secrets | Scan for secrets against baseline |
Dependency Management
| Tool | Ecosystem | Purpose |
| Poetry | Python | Dependency resolution and virtual environments |
| npm | Node.js | Frontend package management |
| Dependabot | Both | Weekly automated dependency updates and security patches |
Configuration Files
Key configuration files in the repository:
| File | Purpose |
pyproject.toml | Python project metadata, dependencies, tool configuration (Ruff, Black, pytest) |
docker-compose.yml | Local development service definitions |
alembic.ini | Alembic migration configuration |
mkdocs.yml | Documentation site configuration |
.pre-commit-config.yaml | Pre-commit hook definitions |
.github/workflows/*.yml | CI/CD pipeline definitions |
.github/dependabot.yml | Automated dependency update configuration |
.mcp.json | MCP server configuration for development tooling |
.env | Local environment variables (not committed) |
.secrets.baseline | detect-secrets baseline for intentional secrets |
Version Compatibility Notes
bcrypt Pinning
bcrypt 5.x is incompatible with passlib 1.7.4. The project pins bcrypt = "<5.0.0" in pyproject.toml to maintain compatibility.
PyTorch Platform Constraint
PyTorch is constrained to python >= 3.11, < 3.14 to ensure compatibility with the sentence-transformers embedding model.
Valkey vs Redis
The project uses Valkey 8 (a Redis-compatible fork) in Docker but continues to use the redis Python client library. All Redis clients work with Valkey without modification. Connection URLs use the redis:// protocol scheme.