Universal Engineering Standards & Quality Gates
This document formalizes the software engineering standards and quality guidelines established by the French Interministerial Digital Directorate (DINUM), beta.gouv.fr, and La Suite Numérique.
📚 1. Official Canonical References & Handbooks
All contributions across this monorepo must adhere to the official state references:
La Suite Developer Handbook
Official developer handbook for La Suite numérique (Architecture, code reviews, accessibility, and security).
Python Best Practices Guide
Python coding standards, typing, Django/DRF architecture, and import organization.
DesignGouv — Accessibility Memo
Digital accessibility checklists and developer memo from the French government.
beta.gouv.fr Quality Standards
Public service standards: uniform code, mandatory automated tests, and product documentation.
La Suite UI Kit
Official UI component library for La Suite applications (@gouvfr-lasuite/ui-components).
La Suite Security Rules
Secrets hygiene, defensive anti-SSRF validation, defense in depth, and permissions.
🎯 2. Strict Precedence of Rules
When technical guidelines appear to conflict across repositories, apply this strict precedence order:
💡 Example : The historical La Suite handbook suggests PEP 8 with 99-character line lengths, whereas modern La Suite repositories configure Ruff with 88 characters. Local repository configuration always wins.
⚛️ 3. Frontend Standards (React, TypeScript & DSFR)
Pre-flight Inspection
- Inspect
package.json,tsconfig.json, and ESLint/Prettier configurations before authoring code. - Reuse existing primitives (
@codegouvfr/react-dsfr,@openfun/cunningham-tokens) rather than introducing redundant packages.
Strict TypeScript
- Zero
anyand zero unsafe type assertions (as ...) without technical documentation. - Explicitly model nullable and optional states (
null | undefined). - Provide complete prop types and API response schemas.
React Component Architecture
- Single-responsibility, cohesive components.
- Derive state during render instead of creating synchronized
useEffectchains. - Explicitly handle all 6 UI states: Initial, Loading, Success, Empty, Recoverable Error, Disabled.
RGAA v4.1 AA Accessibility & Axe-Core
- Native semantic HTML elements (
<button>,<a>,<nav>,<main>,<dialog>) before ARIA. - 100% keyboard navigable with visible focus indicators and explicit focus traps for modals.
- Text contrast ratio $\ge 4.5:1$ and UI components contrast $\ge 3:1$.
- Validation: All user-facing components must pass automated Playwright E2E tests executing
@axe-core/playwrightwith 0 Axe-Core violations.
🐍 4. Backend Standards (Python, Django & Security)
Code Style & Imports
- Enforce automated formatters and linters (Ruff / Black / isort).
- Group imports into 6 logical blocks:
__future__, standard library, frameworks (Django/DRF), third-party libraries, first-party modules, and local imports.
Django & Database Robustness
- Eliminate $N+1$ query overhead with
select_related()andprefetch_related(). - Wrap critical multi-table operations in atomic transactions (
transaction.atomic). - Ensure safe, backward-compatible, and idempotent database migrations.
Defensive Security
- Zero plaintext credentials or hard-coded tokens.
- Mandatory anti-SSRF IP filtering on all outbound network requests.
- Circuit breaker with strict timeouts (e.g. 3.5s) on external APIs.
🔗 5. Canonical URLs & Resources
- Automation & CI:
- Review the monorepo's GitHub CI Workflow.
- Execute the full verification suite locally via
make check.
- Digital Public Goods (DPG):
- Read more about the 9 criteria of the Digital Public Goods Alliance.
- beta.gouv.fr Standards:
- La Suite Numérique: