✨(pcdbapi) introduce a REST API acting as MongoDB proxy to avoid direct connections

Author: sylvinus

.env.development

@@ -6,3 +6,6 @@ NEXT_PUBLIC_MATOMO_URL=""
 NEXT_PUBLIC_MATOMO_SITE_ID=""
 NEXT_PUBLIC_APP_REPOSITORY_URL="https://github.com/numerique-gouv/espace-partenaire"
 NEXT_PUBLIC_BASE_PATH=""
+PCDB_API_URL="http://localhost:8000"
+PCDB_API_SECRET="pcdb-api-secret-key"
+MONGODB_CONNECTION_STRING=mongodb://fc:pass@localhost:27017/core-fca-low?authSource=admin&replicaSet=rs0&directConnection=true

.gitignore

@@ -69,3 +69,10 @@ prisma/generated_clients/
 
 # MongoDB keyfile
 docker/mongodb/mongodb-keyfile
+
+# Python
+__pycache__/
+.pytest_cache/
+*.pyc
+.ruff_cache/
+.coverage

.husky/pre-commit

@@ -1 +1 @@
-npm test
+npm run lint && npm test

README.md

@@ -34,3 +34,9 @@ npm run test
 # lancer les tests end-to-end
 npm run e2e --ui
 ```
+
+### Documentation
+
+La documentation est disponible dans le dossier `docs`.
+
+- [Architecture](docs/architecture.md)

docker-compose.yml

@@ -9,6 +9,7 @@ services:
     ports:
       - "5432:5432"
 
+  # This MongoDB will be seeded with mock data at each restart
   mongodb:
     image: mongo:5.0.23
     environment:
@@ -23,6 +24,39 @@ services:
       - /data/db
       - /data/configdb
 
+  pcdbapi:
+    build: ./pcdbapi
+    environment:
+      - MONGODB_URL=mongodb://fc:pass@mongodb:27017/core-fca-low?authSource=admin&replicaSet=rs0&directConnection=true
+      - API_SECRET=pcdb-api-secret-key
+      - CANT_RUN_TESTS=1
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./pcdbapi:/app
+    depends_on:
+      - mongodb
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    command: uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+
+  pcdbapi-test:
+    build:
+      context: ./pcdbapi
+      dockerfile: Dockerfile.test
+    pull_policy: build
+    profiles: ["test"]
+    volumes:
+      - ./pcdbapi:/app
+    environment:
+      - MONGODB_URL=mongodb://fc:pass@mongodb:27017/proconnect_test?authSource=admin&replicaSet=rs0
+      - API_SECRET=pcdb-api-secret-key
+    depends_on:
+      - mongodb
+
   mailcatcher:
     image: maildev/maildev:2.2.1
     ports:

docs/architecture.md

@@ -0,0 +1,107 @@
+# Architecture Documentation
+
+## Overview
+
+The project consists of three main components:
+
+1. Next.js Frontend - User interface and client-side logic
+2. Next.js API - Backend proxy and session management
+3. FastAPI Service (PCDBAPI) - MongoDB access and data validation
+
+## Component Architecture
+
+```
+├── src/                    # Next.js Frontend & API
+│   ├── pages/
+│   │   ├── api/           # Next.js API Routes
+│   │   │   ├── apps/      # OIDC Client management
+│   │   │   └── auth/      # Authentication
+│   │   └── apps/          # Frontend pages
+│   ├── components/        # React components
+│   └── lib/              # Shared utilities
+│
+└── pcdbapi/              # FastAPI Service
+    ├── main.py           # API endpoints
+    └── middleware.py     # Authentication
+```
+
+## Next.js Frontend
+
+### Core Features
+
+- React-based UI with @codegouvfr/react-dsfr
+- Client-side state management
+- Form handling and validation
+- Compile-time Markdown rendering of files in `src/pages/docs`
+
+### State Management
+
+- Per-page React state
+- No global state store
+- Optimistic updates
+- Debounced saves
+
+## Next.js API
+
+### Responsibilities
+
+- Session management with NextAuth.js
+- Request authentication
+- Proxy to PCDBAPI
+- Error handling
+
+### Routes
+
+- `/api/apps/*` - OIDC client management
+- `/api/auth/*` - Authentication endpoints
+
+### Security
+
+- Server-side sessions
+- Protected routes
+- Request validation
+- Error boundaries
+
+## PCDBAPI Service
+
+### Core Features
+
+- MongoDB access layer
+- Simple, auditable code with 100% test coverage
+
+### Data Model
+
+The data model is strictly enforced by Pydantic models, see `pcdbapi/main.py`.
+
+### Security
+
+- HMAC-SHA256 request signing
+- Email-based access control
+- Timestamp validation (5-min window)
+
+### API Endpoints
+
+- `GET /api/oidc_clients` - List clients
+- `GET /api/oidc_clients/{id}` - Get client
+- `POST /api/oidc_clients` - Create client
+- `PATCH /api/oidc_clients/{id}` - Update client
+
+## Authentication Flow
+
+1. User -> Next.js Frontend
+
+   - Magic link authentication via email
+   - No password required
+   - Secure token in email link
+
+2. Next.js Frontend -> Next.js API
+
+   - NextAuth.js session management
+   - HTTP-only session cookie
+   - Protected routes
+
+3. Next.js API -> PCDBAPI
+   - Request signing with HMAC-SHA256
+   - Timestamp validation (5-min window)
+   - Email ownership validation
+   - Data validation

docs/best-practices.md

@@ -0,0 +1,17 @@
+# Best Practices for code in this project
+
+## General guidelines
+
+- Use types everywhere
+- KISS: Keep It Simple Stupid
+- DRY: Don't Repeat Yourself
+- Don't include unnecessary third party libraries
+
+## Next.js
+
+- Follow the Next.js best practices
+
+## FastAPI
+
+- Follow the FastAPI best practices
+- Full test coverage

package.json

@@ -18,15 +18,17 @@
     "build": "next build && npm run prod:prune",
     "prod:prune": "find node_modules -type f -name '*.map' -delete && rm -rf .next/cache",
     "start": "next start",
-    "lint": "prettier --write '**/*.{ts,tsx,css,md,mdx,mjs,js}' && next lint --no-cache && npm run type-check",
+    "lint": "prettier --write '**/*.{ts,tsx,css,md,mdx,mjs,js}' && next lint --no-cache && npm run type-check && npm run lint:pcdbapi",
+    "lint:pcdbapi:test": "docker-compose run -T --rm pcdbapi-test sh -c 'ruff check . && ruff format --check .'",
+    "lint:pcdbapi": "docker-compose run -T --rm pcdbapi-test sh -c 'ruff check --fix . && ruff format .'",
     "e2e": "NEXT_PUBLIC_BASE_PATH='' NODE_ENV=production npm run build && npm run playwright test",
-    "test": "npm run test:lint",
+    "test": "npm run test:lint && npm run test:pcdbapi",
     "test:unit": "vitest run",
     "test:watch": "vitest watch",
     "test:lint": "prettier '**/*.{ts,tsx,css,md,mdx,mjs,js}' --list-different && next lint --no-cache && npm run type-check",
     "test:links": "start-server-and-test 'npm run dev' 3000 'linkinator 'http://localhost:3000' --recurse --skip \"^(?!http://localhost:3000)\"'",
+    "test:pcdbapi": "docker-compose run -T --rm pcdbapi-test pytest -vv --cov=. --cov-report term-missing --cov-fail-under=100",
     "type-check": "tsc --noEmit",
-    "type-check:watch": "npm run type-check -- --watch",
     "db_espace:reset": "dotenv -e .env.local -- prisma db push --schema=./prisma/db_espace.prisma",
     "db_espace:browse": "dotenv -e .env.local -- prisma studio --schema=./prisma/db_espace.prisma",
     "db_proconnect:browse": "dotenv -e .env.local -- prisma studio --schema=./prisma/db_proconnect.prisma",

pcdbapi/.dockerignore

@@ -0,0 +1,8 @@
+test_*.py
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.pyc
+Dockerfile.test
+Dockerfile
+.coverage

pcdbapi/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.13.2-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY pyproject.toml .
+RUN pip install .
+
+# Copy source code
+COPY . .
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]