# eballester/certtools architecture

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

- Interactive diagram: https://gitdiagram.com/eballester/certtools
- Repository: https://github.com/eballester/certtools

## Overview

1. **Project type and purpose**
   - CertTools is a small, file-processing web application focused on certificate operations: building **PFX/PKCS#12** bundles and **removing passwords** from private keys or PFX files.
   - The architecture is intentionally simple: a browser UI talks to a FastAPI backend that runs OpenSSL-based transformations.

2. **Top-level split: frontend vs backend**
   - The repository is divided into a **static frontend** (`frontend/`) and a **Python backend** (`backend/`).
   - The frontend is responsible for user interaction, file selection/drag-and-drop, and showing download results.
   - The backend owns validation, cryptographic checks, file conversion, and cleanup.

3. **Backend application entry point**
   - `backend/main.py` is the FastAPI entry point.
   - It likely creates the API app, wires in the routers, and exposes the service on port **8000** as described in the README.
   - This is the main composition boundary for the backend.

4. **Feature-based backend routing**
   - The backend is split into two domain routers under `backend/routers/`:
     - `pfx_generator.py` for creating PKCS#12/PFX bundles
     - `key_decryptor.py` for password removal / extraction workflows
   - This suggests each tool is isolated as its own API surface rather than being mixed into one handler set.

5. **Shared backend utilities**
   - `backend/utils.py` contains shared helper logic used by both routers.
   - Based on the README, this likely covers temporary file handling, OpenSSL command execution, validation helpers, and common response/download preparation.
   - This is the main internal reuse boundary inside the backend.

6. **PFX generation flow**
   - User uploads certificate material from the frontend.
   - The backend validates PEM formatting, checks that the private key matches the certificate, and verifies chain/CA trust.
   - If validation passes, the backend generates a **.pfx** file and returns it as a downloadable response.
   - This flow is centered around X.509 artifacts and OpenSSL processing.

7. **Password removal / decryption flow**
   - The decryptor route handles two distinct inputs:
     - **Encrypted private keys** (`.key`, `.pem`) and returns a decrypted key.
     - **PFX files** (`.pfx`) and extracts the key/certificate into a **.zip** archive.
   - The ZIP-based output for PFX decryption is a deliberate UX boundary to avoid import issues with passwordless PFX files.

8. **Frontend architecture**
   - The frontend is a plain static client: `index.html`, `style.css`, and `script.js`.
   - `script.js` is the bridge to the backend API, handling upload interactions and response downloads.
   - There is no frontend framework or client-side state system visible in the tree, so the UI is likely lightweight and purpose-built.

9. **Processing model and security boundary**
   - All sensitive processing happens server-side in **temporary directories** only.
   - The README explicitly says files are deleted immediately after the output is generated and nothing is persisted to disk or a database.
   - This means the primary security boundary is “browser upload → ephemeral backend processing → download response.”

10. **External dependency model**
   - The main runtime dependency is **Python 3.9+** with **FastAPI/Uvicorn** and **OpenSSL** available.
   - The core cryptographic work appears to be delegated to standard OpenSSL commands rather than custom crypto code, which keeps the architecture simple and auditable.

11. **Deployment packaging**
   - The project is containerized with a `Dockerfile`, and `docker-compose.yml` is available for local orchestration.
   - The documented runtime model is a single container exposing port **8000**.
   - This suggests the app is designed as one self-contained service rather than multiple deployable services.

12. **CI/CD and distribution**
   - `.github/workflows/docker-publish.yml` indicates automated Docker image publishing.
   - The deployment artifact is therefore likely the container image, not a packaged Python wheel or frontend bundle.

13. **What to show in an architecture diagram**
   - The main diagram should have:
     - **Browser/UI**
     - **FastAPI backend**
     - Two backend feature modules: **PFX Generator** and **Key Decryptor**
     - A **shared utilities layer**
     - **OpenSSL / system crypto tools**
     - **Temporary filesystem workspace**
   - The key arrow is from UI uploads to backend processing and back as downloadable files, with no database in the middle.

14. **Key architectural constraint**
   - This is a **stateless, request/response, file-transform service**.
   - There are no long-lived user sessions, persistence layer, or asynchronous job queue visible in the repository.
   - That keeps the design compact and makes each request self-contained from upload to cleanup.

Main entry points: [`backend/main.py`](https://github.com/eballester/certtools/blob/main/backend/main.py) (FastAPI App), [`backend/utils.py`](https://github.com/eballester/certtools/blob/main/backend/utils.py) (Shared Utils), [`frontend/script.js`](https://github.com/eballester/certtools/blob/main/frontend/script.js) (Client Bridge), [`backend/routers/pfx_generator.py`](https://github.com/eballester/certtools/blob/main/backend/routers/pfx_generator.py) (PFX Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser_ui["Browser UI<br/>static client<br/>[index.html]"]
  node_frontend_script["Client Bridge<br/>ui logic<br/>[script.js]"]
  node_frontend_style["Styles<br/>presentation<br/>[style.css]"]
end

subgraph group_backend["Backend"]
  node_backend_app["FastAPI App<br/>api entry<br/>[main.py]"]
  node_pfx_router["PFX Generator<br/>route module<br/>[pfx_generator.py]"]
  node_decrypt_router["Key Decryptor<br/>route module<br/>[key_decryptor.py]"]
  node_backend_utils["Shared Utils<br/>helpers<br/>[utils.py]"]
  node_openssl_tooling{{"OpenSSL<br/>system crypto"}}
  node_temp_workspace[("Temp Workspace<br/>ephemeral storage")]
  node_download_response["Downloads<br/>file response"]
end

subgraph group_delivery["Delivery"]
  node_dockerfile["Dockerfile<br/>container build"]
  node_compose["Compose<br/>local orchestration<br/>[docker-compose.yml]"]
  node_workflow["Publish Workflow<br/>ci pipeline<br/>[docker-publish.yml]"]
  node_requirements["Dependencies<br/>python deps<br/>[requirements.txt]"]
end

node_browser_ui -->|"interacts with"| node_frontend_script
node_frontend_script -->|"API calls"| node_backend_app
node_backend_app -->|"mounts"| node_pfx_router
node_backend_app -->|"mounts"| node_decrypt_router
node_pfx_router -->|"uses"| node_backend_utils
node_decrypt_router -->|"uses"| node_backend_utils
node_backend_utils -->|"executes"| node_openssl_tooling
node_backend_utils -->|"writes to"| node_temp_workspace
node_pfx_router -->|"returns"| node_download_response
node_decrypt_router -->|"returns"| node_download_response
node_frontend_script -->|"triggers download"| node_download_response
node_dockerfile -->|"packages"| node_backend_app
node_compose -->|"runs"| node_dockerfile
node_workflow -->|"builds"| node_dockerfile
node_requirements -->|"supplies deps"| node_backend_app

click node_browser_ui "https://github.com/eballester/certtools/blob/main/frontend/index.html"
click node_frontend_script "https://github.com/eballester/certtools/blob/main/frontend/script.js"
click node_frontend_style "https://github.com/eballester/certtools/blob/main/frontend/style.css"
click node_backend_app "https://github.com/eballester/certtools/blob/main/backend/main.py"
click node_pfx_router "https://github.com/eballester/certtools/blob/main/backend/routers/pfx_generator.py"
click node_decrypt_router "https://github.com/eballester/certtools/blob/main/backend/routers/key_decryptor.py"
click node_backend_utils "https://github.com/eballester/certtools/blob/main/backend/utils.py"
click node_dockerfile "https://github.com/eballester/certtools/tree/main/Dockerfile"
click node_compose "https://github.com/eballester/certtools/blob/main/docker-compose.yml"
click node_workflow "https://github.com/eballester/certtools/blob/main/.github/workflows/docker-publish.yml"
click node_requirements "https://github.com/eballester/certtools/blob/main/requirements.txt"

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_ui,node_frontend_script,node_frontend_style toneBlue
class node_backend_app,node_pfx_router,node_decrypt_router,node_backend_utils,node_openssl_tooling,node_temp_workspace,node_download_response toneAmber
class node_dockerfile,node_compose,node_workflow,node_requirements toneMint
```

## Components

### Frontend

Static browser client for upload, conversion requests, and downloads.

- [Browser UI](https://github.com/eballester/certtools/blob/main/frontend/index.html): static client · User-facing page for selecting files and starting certificate workflows. · `frontend/index.html`
- [Client Bridge](https://github.com/eballester/certtools/blob/main/frontend/script.js): ui logic · Handles upload interactions and calls the backend API. · `frontend/script.js`
- [Styles](https://github.com/eballester/certtools/blob/main/frontend/style.css): presentation · Visual styling for the static client. · `frontend/style.css`

### Backend

FastAPI application and feature routers for certificate transforms.

- [FastAPI App](https://github.com/eballester/certtools/blob/main/backend/main.py): api entry · Composes the backend service and exposes the HTTP API. · `backend/main.py`
- [PFX Generator](https://github.com/eballester/certtools/blob/main/backend/routers/pfx_generator.py): route module · API surface for building PKCS#12 / PFX bundles. · `backend/routers/pfx_generator.py`
- [Key Decryptor](https://github.com/eballester/certtools/blob/main/backend/routers/key_decryptor.py): route module · API surface for password removal and extraction workflows. · `backend/routers/key_decryptor.py`
- [Shared Utils](https://github.com/eballester/certtools/blob/main/backend/utils.py): helpers · Common validation, temp-file, and OpenSSL orchestration helpers. · `backend/utils.py`
- **OpenSSL**: system crypto · External command-line crypto engine used for certificate transformations.
- **Temp Workspace**: ephemeral storage · Short-lived filesystem area used for request-scoped processing and cleanup.
- **Downloads**: file response · Generated PFX, key, or ZIP outputs returned to the browser.

### Delivery

Containerization and automated image publishing.

- [Dockerfile](https://github.com/eballester/certtools/tree/main/Dockerfile): container build · Builds the single-service container image. · `Dockerfile`
- [Compose](https://github.com/eballester/certtools/blob/main/docker-compose.yml): local orchestration · Runs the service locally as a containerized app. · `docker-compose.yml`
- [Publish Workflow](https://github.com/eballester/certtools/blob/main/.github/workflows/docker-publish.yml): ci pipeline · Automates Docker image publication. · `.github/workflows/docker-publish.yml`
- [Dependencies](https://github.com/eballester/certtools/blob/main/requirements.txt): python deps · Python runtime and package requirements for the backend service. · `requirements.txt`

## Connections

- Browser UI → Client Bridge: interacts with · The page and scripts coordinate upload and download behavior.
- Client Bridge → FastAPI App: API calls · The client sends file-processing requests to the FastAPI backend.
- FastAPI App → PFX Generator: mounts · The application wires in the PFX generation routes.
- FastAPI App → Key Decryptor: mounts · The application wires in the key decryption routes.
- PFX Generator → Shared Utils: uses · Generation logic shares validation and file-handling helpers.
- Key Decryptor → Shared Utils: uses · Decrypt/extract logic shares validation and file-handling helpers.
- Shared Utils → OpenSSL: executes · Shared helpers delegate cryptographic work to OpenSSL.
- Shared Utils → Temp Workspace: writes to · Processing happens in request-scoped temporary files only.
- PFX Generator → Downloads: returns · Successful generation produces a downloadable PFX file.
- Key Decryptor → Downloads: returns · Successful decryption returns a key or ZIP archive.
- Client Bridge → Downloads: triggers download · The browser downloads the generated artifact from the response.
- Dockerfile → FastAPI App: packages · The container image bundles the backend service.
- Compose → Dockerfile: runs · Local orchestration starts the built container.
- Publish Workflow → Dockerfile: builds · CI publishes the container image from the Docker build.
- Dependencies → FastAPI App: supplies deps · Python packages support the FastAPI backend runtime.