Sirena

a.k.a. SI reclamation

🚀 Getting Started

To use the project locally, make sure the following tools are installed:

• pnpm — for dependency management
• Docker — for running PostgreSQL locally
• Gitleaks — for pre-commit secret detection

To run the project locally, you’ll need a .env file at the root of the repo.

You can start by copying the example:

cp .env.example .env

and edit .env as needed (at least the PG_* variables). you can create an application for the login here to complete the required informations on the frontend .env

Additional environment variables:

• LOG_EXTRA_CONTEXT - Include extra context in logs (tags, comma separated, e.g., foo=bar,baz=bat)
• TRUSTED_IP_HEADERS - Comma-separated list of trusted IP headers (e.g., x-forwarded-for,x-real-ip)

1. Install dependencies

pnpm install

2. launch PostgreSQL

docker compose up
# if first launch (if no migrations add --name <name>)
pnpm db:migrate

2. Generate prisma types

pnpm db:generate

3. Build backend to create rpc

pnpm build:backend

4. Start development servers

pnpm dev

5. create project in ProConnect for login and logout

create your account and project on this url

• Setup your env var with the given Client ID and Client Secret
• Setup http://localhost:5173/api/auth/callback on login url redirection
• Setup http://localhost:5173/login on logout url redirection

📦 Monorepo structure

apps/
├── frontend      → React app using TanStack Router + DSFR + RPC client
├── backend       → API server using Hono + Zod + OpenAPI
packages/
├── ui            → Design system / reusable components (Storybook)

🧪 Commands

Command	Description
pnpm dev	Start frontend + backend in parallel
pnpm dev:frontend	Start frontend (@sirena/frontend)
pnpm dev:backend	Start backend (@sirena/backend) with .env
pnpm dev:backend-utils	Start backend-utils (@sirena/backend-utils)
pnpm dev:common	Start common (@sirena/common)
pnpm dev:ui	Start storybook (@sirena/ui)
pnpm build:backend	Build backend to dist/ (RPC + OpenAPI ready)
pnpm build:frontend	Build frontend to dist/
pnpm build:backend-utils	Build backend-utils to dist/
pnpm build:common	Build common to dist/
pnpm db:migrate	Run dev migrations (@sirena/backend) with .env
pnpm db:migrate:resolve	Run dev migrations (@sirena/backend) with .env
pnpm db:generate	Generate Prisma client from schema (@sirena/backend) with .env
pnpm db:erd	Regenerate the ER diagram docs/prisma.svg from the schema (uses the Chromium downloaded by Puppeteer at install)
pnpm db:erd:check	Verify docs/prisma.svg is up to date with the schema (CI guard-rail)
pnpm op:import:geodata	Import geodata (@sirena/backend) with .env
pnpm op:diff:enums	Check enum consistency (@sirena/backend) with .env. Use --dump-migration for clean SQL output (no logger timestamps), --invert for rollback SQL
pnpm op:import:dematsocial	Import requests from DematSocial (@sirena/backend) with .env
pnpm op:manage-api-keys	Manage third-party API keys (see Third-Party API section)
pnpm op:metabase:export-dashboard	Export a Metabase dashboard + its cards as JSON for repo-tracked backup (see Metabase Dashboard Backup section)
pnpm db:deploy	Deploy pending migrations to DB (@sirena/backend) with .env
pnpm db:studio	Open Prisma Studio (@sirena/backend) with .env
pnpm db:reset	Reset the database (@sirena/backend) with .env
pnpm backend:codegen	Generate clients for graphql requests
pnpm generate:openapi:thirdparty	Generate OpenAPI spec for third-party API (@sirena/backend)
pnpm test:e2e	Run end-to-end tests for frontend (@sirena/frontend)
pnpm test:e2e:ui	Run end-to-end tests with UI for frontend (@sirena/frontend)
pnpm test:unit	Run unit tests across all packages
pnpm lint	Run lint script in all packages (via pnpm -r)
pnpm lint:staged	Run staged file linter in each workspace
pnpm gitleaks:detect-secrets	Scan staged files for secrets using Gitleaks
pnpm gitleaks:update-ignored-secrets	Update the list of ignored secrets for Gitleaks scripts
pnpm prepare	Install Husky Git hooks (called automatically by pnpm install)

🛠️ Tools

🧰 Tooling

• pnpm — Fast, efficient monorepo package manager.
• Docker — Used to run PostgreSQL locally.
• tsc — ESM build system for the backend.
• tsx — Instantly run TypeScript files (used for dev/start/scripts).
• biome — All-in-one linter, formatter, and type checker.
• dotenv-cli — Load .env files when running scripts.
• gitleaks — Secret scanner that prevents committing API keys or credentials.

🧹 Lint

• Biome — Used for formatting, linting, and type checking.
  • Recommended: install the Biome VSCode extension

🧠 Backend

• Hono — Fast, typed web framework.
• Prisma — Type-safe ORM for database modeling and access.
• Zod — Runtime schema validation.
• graffle — Client to make Graphql calls.
• graphql-codegen — Client to generate code for Graphql schemas.

🎨 Frontend

• React — UI library used in the frontend app.
• react-dsfr — Design system based on the French government’s DSFR.
• @tanstack/react-query — Data fetching and caching.
• @tanstack/react-router — Fully typed SPA routing.
• Vite — Fast dev/build tool.

tools

• pnpm
• docker

🔗 Internal packages

Package	Description
@sirena/ui	Reusable design system components (with Storybook)
@sirena/backend	Main Hono backend with OpenAPI + RPC
@sirena/common	package sharing elements from backend end frontend
@sirena/backend-utils	package for exporting element to other projects
@sirena/frontend	Full React SPA using TanStack Router + Query

🔐 Third-Party API, Managing API Keys

Use the CLI tool to manage third-party accounts and API keys:

Create a Third-Party Account

pnpm op:manage-api-keys account create "Partner Company Name"

Returns the account ID.

List All Accounts

pnpm op:manage-api-keys account list

Shows all accounts with their names and key counts.

Create an API Key

pnpm op:manage-api-keys key create <accountId>

List API Keys

# List all keys
pnpm op:manage-api-keys key list

# List keys for specific account
pnpm op:manage-api-keys key list <accountId>

Revoke an API Key

pnpm op:manage-api-keys key revoke <keyId>

Generating the API Key Hash Salt

API keys are hashed using scrypt with a salt provided via the API_KEY_HASH_SALT environment variable. Each environment must have its own unique salt. Generate one with:

openssl rand -hex 32

Store the generated value in the secret store for the target environment. Changing the salt will invalidate all existing API keys.

API Key Format

• Format: sk_{hexadecimal characters}

Using the API

Authentication: Include your API key in the X-API-Key header:

curl -H "X-API-Key: <your API key>" \
  https://your-domain.com/api/third-party/v1

Response Tracing: All API responses include an x-trace-id header for debugging and support purposes. Include this trace ID when reporting issues.

Example response headers:

x-trace-id: 1b6e9a8d-c489-4916-bc83-ef49b3698837
content-type: application/json

The traceId is also included in successful response bodies for convenience.

📊 Metabase Dashboard Backup

The op:metabase:export-dashboard script snapshots a Metabase dashboard (and every card it references) as normalized JSON files under docs/metabase_dashboards/<dashboard-id>/. The output is human-readable, key-sorted, and stripped of volatile metadata so commits produce clean diffs and changes can be reviewed in PRs.

Setup

Add the API key to your local .env (the existing METABASE_SITE_URL, METABASE_DASHBOARD_ID and METABASE_DASHBOARD_ID_ADMIN are reused):

# Metabase Admin → Authentication → API keys (requires Metabase ≥ 0.49)
METABASE_API_KEY=mb_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Usage

# Exports both METABASE_DASHBOARD_ID and METABASE_DASHBOARD_ID_ADMIN from .env
pnpm op:metabase:export-dashboard

# Explicit dashboard id (overrides the env values)
pnpm op:metabase:export-dashboard 4

Output layout

docs/metabase_dashboards/
└── 4/
    ├── dashboard.json        # full dashboard definition (layout, parameters, dashcards)
    └── cards/
        ├── 42.json           # one file per referenced card (SQL, visualization, settings)
        └── 43.json

Diff-friendly normalization

• Object keys sorted alphabetically at every depth
• Stripped fields:
  • Personal data (never committed): creator, last_edit_info / last-edit-info (both embed author email + first/last name)
  • Volatile metadata (diff noise): created_at, updated_at, last_used_at, last_query_started_at, view_count, cache_invalidated_at, initially_published_at
• 2-space indentation with trailing newline

When to run

Commit the regenerated JSON whenever a dashboard or one of its cards is edited in the Metabase UI. The diff shows exactly what changed in the dashboard's definition.

Note: This is an export-only tool. Restoring a dashboard from these JSON is out of scope

Docker build

docker compose -f docker-compose.prod.yaml up

🔄 Git Workflow

Branches

• main : Main development branch

  • All feature branches are created from main
  • Automatic deployment to development environment
  • Should never be deleted

• validation : Validation branch

  • Merge from main at the end of sprints (or more frequently if needed)
  • Deployment to validation environment
  • Hotfixes in validation are pushed to this branch
  • Hotfixes must be backported to main via a PR and merge
  • Should never be deleted

• production : Production branch

  • Merge from validation for production deployments
  • Deployment to production environment
  • Hotfixes in production are pushed to this branch
  • Hotfixes must be backported to validation then main via PRs and merges
  • Should never be deleted