BIP Vigilance

Visit project ↗
  • Integrity
  • Signing
  • SaaS
  • Resilience
Architecture
Strict hexagonal architecture (Ports & Adapters). Parallelized multi-registry verification (SIRENE, BODACC, VIES). AWS KMS sealing (RSA-PSS SHA-256) with public QR code verification.
Stack & Delivery
FastAPI · Next.js 15 · PostgreSQL · Redis. OAuth2 / JWT (ES256) auth. Stripe billing. Deployed on Railway + Vercel.

Designing a KYS platform producing sealed, publicly verifiable reports

Key architectural decisions

  • Asymmetric report signing via AWS KMS (RSA-PSS SHA-256)
  • Public verification without authentication via token
  • Systematic idempotency on costly operations
  • External resilience via retry worker + Redis circuit breaker
  • Strict hexagonal architecture (pure domain, Python Protocol ports)

1. Context

Vigilance is a SaaS supplier compliance platform (Know Your Supplier).

It:

  • queries public sources (INSEE/SIRENE, BODACC, VIES)
  • aggregates compliance signals
  • produces a verdict (GREEN / RED / GREY)
  • generates a cryptographically sealed PDF report
  • enables public authenticity verification without authentication

The goal is not document management. It is the production of technical proof of regulatory compliance.

2. Architectural constraints and challenges

Integrity and non-repudiation

  • SHA-256 hash of PDF content
  • Deterministic canonical payload
  • RSA-PSS SHA-256 asymmetric signature via AWS KMS
  • Non-exportable private key
  • Public verification token (embedded QR code)

Goal: detect any alteration and guarantee the signer’s identity.

Confidentiality

  • Encryption at rest S3 SSE-AES256
  • Access via presigned URL (15 minutes)

Deliberate choice: no end-to-end encryption. Documents are generated server-side. Confidentiality and integrity are treated separately.

Critical traceability

  • Append-only audit log
  • actor, IP, user-agent
  • correlation ID
  • before/after state JSONB

Currently covers: assessment creation and report sealing.

Unstable public APIs

External sources subject to timeouts, 5xx errors and temporary unavailability.

Controlled retry — Exponential backoff up to 48h.

Redis circuit breaker — CLOSED / OPEN / HALF_OPEN triggered by error thresholds.

Idempotency — Idempotency key on assessment creation.

Bitemporal modeling:

  • valid_from / valid_to — business reality
  • sys_from / sys_to — system reality

Enables reconstructing the legal state at a given date and auditing what the system knew at the time of the report.

Multi-tenant SaaS

  • Application-level isolation CustomerAccount + Membership
  • 3 modes: INDIVIDUAL / SELF / ON_BEHALF
  • No DB isolation — deliberate trade-off of operational simplicity over physical isolation

3. Key architecture decisions

Signing via AWS KMS

KMS used for asymmetric signing — not for encryption.

Pipeline:

  1. PDF generation via Playwright
  2. SHA-256 hash
  3. Canonical payload
  4. KMS signature
  5. Atomic persistence (S3 + DB + token + audit)

The private key never leaves KMS.

Strict hexagonal architecture

  • Pure immutable domain
  • Ports via Python Protocol
  • Adapters for infrastructure and security

Security is injected without polluting business logic.

Idempotency as a critical guard

Protects against:

  • double sealing
  • double network cost
  • business inconsistencies

Circuit breaker positioned on recovery

Initial failure is accepted. Resilience is ensured by the controlled retry flow.

Public verification

Unauthenticated token allowing a third party to verify the authenticity of a report.

4. Security and access

Authentication

  • OAuth2 PKCE multi-provider
  • DPoP for machine-to-machine
  • httpOnly cookies
  • CSRF double submit cookie

Contractual middleware pipeline

logging → rate limiting → CORS → session → trusted host → CSRF → security headers → correlation ID → locale

Explicit security and observability pipeline.

5. Frontend as an architecture component

  • Public verification without auth
  • Correlation ID propagation
  • CSRF auto-refresh
  • Strict CSP
  • Multi-tenant UI aligned with backend

6. SaaS mechanisms

Quotas

AVAILABLE → WARNING_80 → EXHAUSTED_PAYABLE → EXHAUSTED_BLOCKED

Checked before creation, deducted after success.

Database

Supporting the above guarantees:

  • Monthly partitioned PostgreSQL
  • Global uniqueness registry
  • JSONB for signals
  • Async everywhere

7. Guarantees and limitations

Technical guarantees

  • Publicly verifiable integrity
  • Critical traceability
  • External resilience
  • Idempotency
  • Application-level isolation

Acknowledged limitations

  • No formal legal framework
  • No load benchmarks
  • Partial flow auditing

8. Architecture lessons

  • Confidentiality ≠ integrity
  • Delegating crypto reduces risk
  • Idempotency is non-negotiable
  • Circuit breaker is essential
  • Bitemporal is essential for legal data
  • Protocol Ports = cleanly injectable security
← Back to list