Skip to content

Tech Stack Overview

This document provides a concise reference to the core technologies used in the CO₂ Calculator project. It focuses on essential facts to minimize maintenance burden. For detailed rationale and alternatives considered, see Architectural Decisions.

Last Updated: 2025-12-11


Core Requirements

  • Open Source: GPL-3.0 license, EPFL owns the code
  • Architecture: Stateless web application (SPA + API), horizontally scalable
  • Deployment: docker-compose (local/dev), Kubernetes / Helm (production)
  • Database: PostgreSQL (production), SQLite (backend unit tests only)
  • Authentication: JWT-based RBAC, pluggable for OIDC/OAuth2

Runtime & Package Management

Backend

  • Language: Python 3.14
  • Package Manager: uv
  • Dependency File: backend/pyproject.toml
  • Lockfile: uv.lock

Frontend


Frontend Stack

Core Technologies

Internationalization resources

  • Build integrates @intlify/unplugin-vue-i18n to load messages from src/i18n/**/*.json and src/assets/i18n/**/*.json|md, with runtimeOnly: false to support named tokens.

Development

Deployment

  • Build Output: Static SPA assets (/dist/spa)
  • Server: Nginx (Alpine-based, port 8080, non-root)
  • Container: Multi-stage build (node:26-alpine → nginx:stable-alpine-slim)

Backend Stack

Core Technologies

Development

Deployment

  • Container: ghcr.io/astral-sh/uv:python3.14-alpine (multi-stage build)
  • Runtime User: appuser (UID/GID 1001, non-root)
  • Exposed Port: 8000

Database Configuration

Development

The PostgreSQL service of Docker Compose (make run-db). DB_URL has no default, and the migrations need PostgreSQL. The backend unit tests use an in-memory SQLite database (ADR-004).

External PostgreSQL 15+ managed service.

Configuration Options

Via pydantic-settings in backend/app/core/config.py:

# Option 1: Full URL (takes precedence)
DB_URL="postgresql://user:pass@host:5432/db"

Migrations: Alembic in backend/alembic/versions (code review required).


Deployment

Local Development

docker-compose with services:

  • backend (FastAPI on port 8000)
  • frontend (Nginx on port 8080)
  • postgres (PostgreSQL 18-alpine)
  • pgadmin (database UI)
  • reverse-proxy (Traefik — routes /api/* to backend, /* to frontend)

Production (Kubernetes)

Helm chart in helm/ with:

  • Backend deployment (2+ replicas, HPA optional)
  • Frontend deployment (2+ replicas, HPA optional)
  • nginx-ingress controller (EPFL standard)
  • TLS via cert-manager
  • External PostgreSQL

Security: Non-root containers, read-only filesystems, no privilege escalation.


CI/CD & Security

Active Workflows (.github/workflows)

  • test.yml: pytest (backend), Playwright (frontend)
  • security.yml: npm audit, uv audit, Bandit, TruffleHog, CodeQL
  • quality-check.yml: ruff, mypy, ESLint, Prettier (PRs)
  • .gitlab-ci.yml (gitlab.epfl.ch): Container builds + Helm chart → ghcr.io + quay for dev, stage and tags, fed by mirror-to-gitlab.yml (plan 2909)
  • deploy-pages.yml: Documentation deployment (GitHub Pages)
  • lighthouse.yml: Frontend performance audits (PRs)
  • release-please.yml: Automated semantic versioning

For complete workflow details, see CI/CD Workflows.

Security Tools

  • SAST: Bandit (Python), CodeQL, ESLint security rules
  • Dependency Scanning: npm audit, uv audit
  • Secrets Detection: TruffleHog (git history scan)

For security scanning details, see CI/CD Pipeline.


Documentation

Zensical at docs/, configured in docs/zensical.toml. Each release is published to GitHub Pages. Supports Markdown, Mermaid diagrams and search.


Performance & Scaling

Stateless design with JWT-based auth enables horizontal scaling via HPA or manual replica adjustments. Database connection pooling is SQLAlchemy in-process, behind the PgBouncer DBaaS runs in front of every instance — its server pool is the connection ceiling (see the database overview).


  • Architectural Decisions — Detailed rationale for tech choices
  • Deployment Topology — Infrastructure diagrams and patterns
  • CI/CD Pipeline — Workflow details and integration points
  • Frontend: frontend/package.json — Exact dependency versions
  • Backend: backend/pyproject.toml — Exact dependency versions