# contentauth/c2pa-python-example architecture

> Architecture diagram of the GitHub repository contentauth/c2pa-python-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/contentauth/c2pa-python-example
- Repository: https://github.com/contentauth/c2pa-python-example

## Overview

##### Project type and purpose
- This is a backend-only, containerized Python service (no HTML-based front end).
- It exposes a REST endpoint (`POST /attach`) via Flask to accept a JPEG, attach a C2PA manifest, and sign it using a KMS-backed certificate.
- It can run against real AWS KMS or a LocalStack container for local development and testing.

##### File structure
- Top level:
- app.py – Flask application entry point
- setup.py & scripts/ – CLI tasks for generating KMS keys, CSRs, and certificates
- Dockerfile, docker-compose.yaml, Makefile, local-setup.sh – container build & orchestration
- example-env.env / .env – environment-variable templates
- requirements.txt – Python dependencies (Flask, boto3, c2pa-python SDK, waitress, etc.)
- tests/ – integration tests and example client (tests/client.py)
- No “frontend” directory; it’s purely a signing microservice.
- docker-compose.yaml defines four containers:
1. localstack-main (mocked AWS infra)
2. local-setup (one-time infrastructure setup)
3. local-signer (Flask/Waitress signing server)
4. local-client (Python client to self-test signing)

##### Key insights from README
- The service interacts with AWS KMS (or LocalStack) via boto3.
- setup.py automates CSR and key management.
- Docker Compose orchestrates initialization (creating IAM user, KMS key, CSR, certificate chain) before launching the signer and client.

a. Main components:
- API Client (curl or tests/client.py / local-client container)
- Signing Service (Flask app in local-signer container)
- KMS Service (AWS KMS in real AWS or LocalStack in localstack-main container)
- Setup Batch Job (setup.py & local-setup container)
- Certificate Authority (external CA or self-signed root CA)
- Volumes: config_volume (stores CSR, chain.pem, env files), client_volume (signed images)
b. Relationships & interactions:
1. On `make local`, Docker Compose spins up localstack-main → local-setup runs setup.py scripts → writes keys, CSR, chain.pem into config_volume.
2. local-signer starts, reads .env, loads KMS_KEY_ID and chain.pem, serves HTTP on 0.0.0.0:5000.
3. Client (local-client container or external curl) `POST /attach` → Signing Service
4. Signing Service calls KMS via AWS SDK/boto3 (pointed at LocalStack endpoint) to sign nonce or derive keys.
5. Signing Service uses c2pa-python SDK to assemble manifest + signature → returns signed JPEG → client_volume.
c. Architectural patterns & principles:
- Microservices via isolated Docker containers
- Infrastructure as code: setup.py + local-setup.sh automate AWS/LocalStack provisioning
- Clear separation of concerns:
- Setup phase (infrastructure bootstrap)
- Runtime phase (signer service)
- Client testing phase
- Environment-driven configuration (.env, example-env.env)
d. Key technologies/frameworks:
- Python 3.10/3.12, Flask, Waitress (production WSGI), boto3, c2pa-python SDK
- Docker, Docker Compose, LocalStack
- OpenSSL for CSR & certificate chaining (scripts/digicert-create-cert.sh)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Containers"
        subgraph "Setup Phase"
            LocalSetup["local-setup\n(setup.py & scripts)"]:::container
        end
        subgraph "Runtime Phase"
            SigningService["Signing Service\nFlask / Waitress"]:::container
            APIClient["API Client\ntests/client.py or curl"]:::container
        end
        subgraph "Infrastructure"
            LocalStack["LocalStack\nMock AWS KMS"]:::container
            AWSKMS["AWS KMS\n(production)"]:::external
        end
    end

    config_volume[(config_volume)]:::volume
    client_volume[(client_volume)]:::volume
    ExternalCA["External CA\n(root or self-signed)"]:::external
    DockerCompose["docker-compose.yaml & Dockerfile"]:::config
    ExampleEnv["example-env.env\nenv-var-documentation.env"]:::config
    Requirements["requirements.txt"]:::config
    TestsDir["tests/ (integration & client)"]:::config

    DockerCompose --> LocalSetup
    DockerCompose --> LocalStack
    DockerCompose --> SigningService
    DockerCompose --> APIClient

    LocalSetup --"provisions KMS keys\n(boto3 to LocalStack)"--> LocalStack
    LocalSetup --"writes keys, CSR,\nchain.pem (file I/O)"--> config_volume
    ExternalCA --"provides chain.pem"--> config_volume

    config_volume --"mount .env,\nKMS_KEY_ID,\nchain.pem"--> SigningService
    ExampleEnv --> SigningService
    Requirements --> SigningService

    APIClient -->|"POST /attach (HTTP)"| SigningService
    SigningService -->|"HTTP response\n(signed JPEG)"| APIClient

    SigningService -->|"boto3/KMS API"| LocalStack
    SigningService -->|"boto3/KMS API"| AWSKMS
    SigningService --"writes signed JPEG"--> client_volume

    TestsDir --> APIClient

    classDef container fill:#D6EFFF,stroke:#0366D6,stroke-width:1px
    classDef volume fill:#FFF2CC,stroke:#D69F00,stroke-width:1px
    classDef external fill:#E8F0FE,stroke:#1A73E8,stroke-width:1px
    classDef config fill:#E6F4EA,stroke:#34A853,stroke-width:1px

    click APIClient "https://github.com/contentauth/c2pa-python-example/blob/main/tests/client.py"
    click SigningService "https://github.com/contentauth/c2pa-python-example/blob/main/app.py"
    click LocalSetup "https://github.com/contentauth/c2pa-python-example/blob/main/setup.py"
    click DigicertScript "https://github.com/contentauth/c2pa-python-example/blob/main/scripts/digicert-create-cert.sh"
    click LocalSetupScript "https://github.com/contentauth/c2pa-python-example/blob/main/local-setup.sh"
    click DockerCompose "https://github.com/contentauth/c2pa-python-example/blob/main/docker-compose.yaml"
    click Dockerfile "https://github.com/contentauth/c2pa-python-example/tree/main/Dockerfile"
    click ExampleEnv "https://github.com/contentauth/c2pa-python-example/blob/main/example-env.env"
    click EnvDoc "https://github.com/contentauth/c2pa-python-example/blob/main/env-var-documentation.env"
    click Requirements "https://github.com/contentauth/c2pa-python-example/blob/main/requirements.txt"
    click TestsDir "https://github.com/contentauth/c2pa-python-example/tree/main/tests/"
    click TestCerts "https://github.com/contentauth/c2pa-python-example/tree/main/tests/certs/"
```
