# keerthi-gg/dpp architecture

> Architecture diagram of the GitHub repository keerthi-gg/dpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keerthi-gg/dpp
- Repository: https://github.com/keerthi-gg/dpp

## Overview

This is an MVP digital product passport (DPP) backend with a small browser interface. Its core workflow registers a product, looks it up by passport ID or QR reference, records lifecycle transitions, and exposes lifecycle history and regulator reporting. Lifecycle changes validate role, state progression, and a single-use transaction before updating product state and recording an event. The sampled implementation uses singleton in-memory repositories; route-to-service behavior is represented cautiously because router implementations were not excerpted.

Main entry points: [`plastic-dpp-greenfield/backend/app/container.py`](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/container.py) (Service wiring), [`plastic-dpp-greenfield/backend/app/services/lifecycle_service.py`](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/lifecycle_service.py) (Lifecycle service), [`plastic-dpp-greenfield/backend/app/main.py`](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/main.py) (API application), [`plastic-dpp-greenfield/backend/app/routers/lifecycle.py`](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/lifecycle.py) (Lifecycle routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser["DPP interface<br/>[app.js]"]
end

subgraph group_api["HTTP API"]
  node_app["API application<br/>[main.py]"]
  node_product_api["Product routes<br/>[products.py]"]
  node_lifecycle_api["Lifecycle routes<br/>[lifecycle.py]"]
  node_transaction_api["Transaction routes<br/>[transactions.py]"]
  node_report_api["Regulator routes<br/>[regulator.py]"]
  node_identity["Mock role identity<br/>[dependencies.py]"]
end

subgraph group_domain["Domain services"]
  node_product_service["Product service<br/>[product_service.py]"]
  node_lifecycle_service["Lifecycle service"]
  node_ledger["Transaction ledger"]
  node_reporting["Reporting service"]
  node_container["Service wiring<br/>[container.py]"]
end

subgraph group_state["Domain state"]
  node_models["Passport and event models"]
  node_product_store[("Product repository")]
  node_event_store[("Lifecycle event repository")]
  node_transaction_store[("Transaction repository")]
end

node_manufacturer(("Manufacturer"))
node_consumer(("Consumer"))
node_recycler(("Recycler"))
node_regulator(("Regulator"))

node_browser -.->|"sends requests"| node_app
node_manufacturer -.->|"registers products"| node_product_api
node_consumer -.->|"updates ownership"| node_lifecycle_api
node_recycler -.->|"records recycling"| node_lifecycle_api
node_regulator -.->|"requests reports"| node_report_api
node_app -->|"registers routes"| node_product_api
node_app -->|"registers routes"| node_lifecycle_api
node_app -->|"registers routes"| node_transaction_api
node_app -->|"registers routes"| node_report_api
node_product_api -.->|"dispatches to"| node_product_service
node_lifecycle_api -.->|"dispatches to"| node_lifecycle_service
node_transaction_api -.->|"dispatches to"| node_ledger
node_report_api -.->|"dispatches to"| node_reporting
node_lifecycle_api -.->|"resolves caller"| node_identity
node_product_api -.->|"resolves caller"| node_identity
node_lifecycle_service -->|"requires product"| node_product_service
node_lifecycle_service -->|"validates transaction"| node_ledger
node_lifecycle_service -->|"records events"| node_event_store
node_lifecycle_service -->|"updates product"| node_product_store
node_product_service -->|"reads and writes"| node_product_store
node_ledger -->|"reads and writes"| node_transaction_store
node_reporting -->|"reads products"| node_product_service
node_container -->|"constructs"| node_product_service
node_container -->|"constructs"| node_lifecycle_service
node_container -->|"constructs"| node_ledger
node_container -->|"constructs"| node_reporting
node_container -->|"constructs"| node_product_store
node_container -->|"constructs"| node_event_store
node_container -->|"constructs"| node_transaction_store

click node_browser "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/static/app.js"
click node_app "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/main.py"
click node_product_api "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/products.py"
click node_lifecycle_api "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/lifecycle.py"
click node_transaction_api "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/transactions.py"
click node_report_api "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/regulator.py"
click node_identity "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/dependencies.py"
click node_product_service "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/product_service.py"
click node_lifecycle_service "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/lifecycle_service.py"
click node_ledger "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/transaction_service.py"
click node_reporting "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/reporting_service.py"
click node_models "https://github.com/keerthi-gg/dpp/tree/main/plastic-dpp-greenfield/backend/app/models"
click node_product_store "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/storage/product_repository.py"
click node_event_store "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/storage/lifecycle_repository.py"
click node_transaction_store "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/storage/transaction_repository.py"
click node_container "https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/container.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser toneBlue
class node_app,node_product_api,node_lifecycle_api,node_transaction_api,node_report_api,node_identity toneAmber
class node_product_service,node_lifecycle_service,node_ledger,node_reporting,node_container toneMint
class node_models,node_product_store,node_event_store,node_transaction_store toneRose
class node_manufacturer,node_consumer,node_recycler,node_regulator toneIndigo
```

## Components

### Client

- [DPP interface](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/static/app.js): `plastic-dpp-greenfield/backend/static/app.js`

### HTTP API

- [API application](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/main.py): `plastic-dpp-greenfield/backend/app/main.py`
- [Product routes](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/products.py): `plastic-dpp-greenfield/backend/app/routers/products.py`
- [Lifecycle routes](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/lifecycle.py): `plastic-dpp-greenfield/backend/app/routers/lifecycle.py`
- [Transaction routes](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/transactions.py): `plastic-dpp-greenfield/backend/app/routers/transactions.py`
- [Regulator routes](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/regulator.py): `plastic-dpp-greenfield/backend/app/routers/regulator.py`
- [Mock role identity](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/routers/dependencies.py): `plastic-dpp-greenfield/backend/app/routers/dependencies.py`

### Domain services

- [Product service](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/product_service.py): `plastic-dpp-greenfield/backend/app/services/product_service.py`
- [Lifecycle service](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/lifecycle_service.py): `plastic-dpp-greenfield/backend/app/services/lifecycle_service.py`
- [Transaction ledger](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/transaction_service.py): `plastic-dpp-greenfield/backend/app/services/transaction_service.py`
- [Reporting service](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/services/reporting_service.py): `plastic-dpp-greenfield/backend/app/services/reporting_service.py`
- [Service wiring](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/container.py): `plastic-dpp-greenfield/backend/app/container.py`

### Domain state

- [Passport and event models](https://github.com/keerthi-gg/dpp/tree/main/plastic-dpp-greenfield/backend/app/models): `plastic-dpp-greenfield/backend/app/models`
- [Product repository](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/storage/product_repository.py): `plastic-dpp-greenfield/backend/app/storage/product_repository.py`
- [Lifecycle event repository](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/storage/lifecycle_repository.py): `plastic-dpp-greenfield/backend/app/storage/lifecycle_repository.py`
- [Transaction repository](https://github.com/keerthi-gg/dpp/blob/main/plastic-dpp-greenfield/backend/app/storage/transaction_repository.py): `plastic-dpp-greenfield/backend/app/storage/transaction_repository.py`

### Other components

- **Manufacturer**
- **Consumer**
- **Recycler**
- **Regulator**

## Connections

- DPP interface → API application: sends requests
- Manufacturer → Product routes: registers products
- Consumer → Lifecycle routes: updates ownership
- Recycler → Lifecycle routes: records recycling
- Regulator → Regulator routes: requests reports
- API application → Product routes: registers routes (evidence: `plastic-dpp-greenfield/backend/app/main.py`)
- API application → Lifecycle routes: registers routes (evidence: `plastic-dpp-greenfield/backend/app/main.py`)
- API application → Transaction routes: registers routes (evidence: `plastic-dpp-greenfield/backend/app/main.py`)
- API application → Regulator routes: registers routes (evidence: `plastic-dpp-greenfield/backend/app/main.py`)
- Product routes → Product service: dispatches to (evidence: `plastic-dpp-greenfield/backend/app/routers/products.py`)
- Lifecycle routes → Lifecycle service: dispatches to (evidence: `plastic-dpp-greenfield/backend/app/routers/lifecycle.py`)
- Transaction routes → Transaction ledger: dispatches to (evidence: `plastic-dpp-greenfield/backend/app/routers/transactions.py`)
- Regulator routes → Reporting service: dispatches to (evidence: `plastic-dpp-greenfield/backend/app/routers/regulator.py`)
- Lifecycle routes → Mock role identity: resolves caller (evidence: `plastic-dpp-greenfield/backend/app/routers/lifecycle.py`)
- Product routes → Mock role identity: resolves caller (evidence: `plastic-dpp-greenfield/backend/app/routers/products.py`)
- Lifecycle service → Product service: requires product (evidence: `plastic-dpp-greenfield/backend/app/services/lifecycle_service.py`)
- Lifecycle service → Transaction ledger: validates transaction (evidence: `plastic-dpp-greenfield/backend/app/services/lifecycle_service.py`)
- Lifecycle service → Lifecycle event repository: records events (evidence: `plastic-dpp-greenfield/backend/app/services/lifecycle_service.py`)
- Lifecycle service → Product repository: updates product (evidence: `plastic-dpp-greenfield/backend/app/services/lifecycle_service.py`)
- Product service → Product repository: reads and writes (evidence: `plastic-dpp-greenfield/backend/app/services/product_service.py`)
- Transaction ledger → Transaction repository: reads and writes (evidence: `plastic-dpp-greenfield/backend/app/services/transaction_service.py`)
- Reporting service → Product service: reads products (evidence: `plastic-dpp-greenfield/backend/app/services/reporting_service.py`)
- Service wiring → Product service: constructs (evidence: `plastic-dpp-greenfield/backend/app/container.py`)
- Service wiring → Lifecycle service: constructs (evidence: `plastic-dpp-greenfield/backend/app/container.py`)
- Service wiring → Transaction ledger: constructs (evidence: `plastic-dpp-greenfield/backend/app/container.py`)
- Service wiring → Reporting service: constructs (evidence: `plastic-dpp-greenfield/backend/app/container.py`)
- Service wiring → Product repository: constructs (evidence: `plastic-dpp-greenfield/backend/app/container.py`)
- Service wiring → Lifecycle event repository: constructs (evidence: `plastic-dpp-greenfield/backend/app/container.py`)
- Service wiring → Transaction repository: constructs (evidence: `plastic-dpp-greenfield/backend/app/container.py`)
