CA/PKI Backend Project Context
Stack
•	Python 3.13
•	FastAPI (web API)
•	psycopg (PostgreSQL driver)
•	PostgreSQL database: ca
•	Unit tests: unittest
•	HTTP testing: fastapi.testclient
•	Zenroom cryptographic runtime (Docker container)
Run tests:
python3 -m unittest discover
Integration tests require:
export DATABASE_URL="postgresql:///ca"
—————
Project Structure
pki/
├── ca_core/
│   ├── entity.py
│   ├── group_member.py
│   ├── property.py
│   ├── metadata.py
│   ├── db_logging.py
│   └── crypto/
│       ├── zenroom_client.py
│       └── zenroom_service_client.py
│
├── ca_api/
│   ├── app.py
│   └── db.py
│
├── tests/
│   ├── test_entity.py
│   ├── test_group.py
│   ├── test_property.py
│   ├── test_metadata.py
│   ├── test_api_smoke.py
│   ├── test_api_unit.py
│   ├── test_api_integration.py
│   └── integration/
│       └── zenroom tests
│
├── create_tables.sql
└── PROJECT_CONTEXT.md
—————
Architecture
HTTP API (FastAPI)
        │
        ▼
ca_api (thin HTTP adapter)
        │
        ▼
ca_core (business logic)
        │
        ▼
PostgreSQL
The system is layered to keep business logic independent from the HTTP interface.
—————
Database Overview
Database: ca
Core tables:
•	entity
•	group_member
•	property
•	metadata
•	log
Entity Rules
Entity types:
•	person
•	group
•	device
Status values:
•	active
•	revoked
Groups must include ca_reference.
Persons and devices must not include ca_reference.
Revoked entities are immutable.
—————
Logging
All mutations must call:
log_change(cursor, message)
Exactly one log entry must be produced per mutation.
Logging occurs inside the same transaction.
—————
Core Modules
entity.py
Provides:
•	insert_creator
•	enroll_person
•	create_group
•	get_entity
•	set_entity_status
group_member.py
Provides:
•	add_group_member
•	remove_group_member
•	get_members_of_group
property.py
Provides:
•	set_property
•	delete_property
•	get_properties
metadata.py
Provides:
•	get_name
•	get_comment
•	get_public_key
•	get_defense_p
•	set_name
•	set_defense_p
—————
Cryptographic Layer
The system integrates Zenroom for cryptographic operations.
Zenroom runs in an isolated environment, typically a Docker container.
ca_core
   │
   ▼
crypto clients
   │
   ▼
Zenroom runtime
zenroom_client.py
Local execution interface.
Responsibilities:
•	execute Zenroom scripts
•	parse output
•	raise errors
Used for development and some integration tests.
zenroom_service_client.py
HTTP client for a Zenroom service container.
Responsibilities:
•	send scripts
•	pass JSON input
•	return parsed result
Typical flow:
Python
   ↓
ZenroomServiceClient
   ↓
HTTP request
   ↓
Zenroom container
   ↓
JSON result
—————
API Layer (ca_api)
FastAPI provides the HTTP interface.
Responsibilities:
•	routing
•	validation
•	DB connection handling
•	error mapping
Flow:
HTTP request
     ↓
FastAPI route
     ↓
db_cursor()
     ↓
ca_core function
     ↓
commit / rollback
—————
Testing Strategy
Three layers of tests exist.
Core Unit Tests
Test domain logic directly.
Examples:
•	test_entity.py
•	test_group.py
•	test_property.py
•	test_metadata.py
API Unit Tests
Test HTTP behaviour without DB.
Mocked components:
•	db_cursor
•	ca_core functions
File:
•	test_api_unit.py
API Integration Tests
Full stack tests:
FastAPI
↓
ca_core
↓
PostgreSQL
File:
•	test_api_integration.py
Requires:
export DATABASE_URL="postgresql:///ca"
Zenroom Integration Tests
Located in:
tests/integration/
Verify:
•	Zenroom script execution
•	service communication
•	error handling
Some tests require a running Zenroom container.
—————
Runtime Deployment Model
FastAPI API
     │
     ▼
ca_core
     │
     ▼
crypto client
     │
     ▼
Zenroom container
     │
     ▼
PostgreSQL
This design keeps cryptographic execution isolated while keeping the Python service lightweight.