# christoph865/certops-agent architecture

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

- Interactive diagram: https://gitdiagram.com/christoph865/certops-agent
- Repository: https://github.com/christoph865/certops-agent

## Overview

CertOps Agent manages certificate and secret lifecycle through a JWT-secured Flask API, with an MCP server exposing API operations to LLM agents. Certificate operations use Key Vault for the live certificate and SQLAlchemy-backed metadata; audit events are mirrored to Azure Storage Tables. A separate daily scan refreshes expiry status and records a summary. The README documents secret management and Entra ID authentication, but their implementation details were not sampled, so those links are shown as unverified where appropriate.

Main entry points: [`app/api/certificates.py`](https://github.com/christoph865/certops-agent/blob/main/app/api/certificates.py) (Certificate API), [`app/services/certificate_service.py`](https://github.com/christoph865/certops-agent/blob/main/app/services/certificate_service.py) (Certificate service), [`app/services/audit_service.py`](https://github.com/christoph865/certops-agent/blob/main/app/services/audit_service.py) (Audit service), [`app/api/secrets.py`](https://github.com/christoph865/certops-agent/blob/main/app/api/secrets.py) (Secret API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_api_app["Flask application<br/>[__init__.py]"]
  node_cert_api["Certificate API<br/>[certificates.py]"]
  node_secret_api["Secret API<br/>[secrets.py]"]
  node_health_api["Health API<br/>[health.py]"]
  node_jwt["JWT access<br/>[extensions.py]"]
end

subgraph group_lifecycle["Certificate lifecycle"]
  node_cert_service["Certificate service"]
  node_cert_model["Certificate metadata<br/>[certificate.py]"]
  node_x509["X.509 utilities<br/>[x509_utils.py]"]
end

subgraph group_secrets["Secret lifecycle"]
  node_secret_service["Secret service<br/>[secret_service.py]"]
  node_key_vault["Key Vault integration"]
end

subgraph group_persistence["Persistence and audit"]
  node_sql[("SQL database")]
  node_audit_service["Audit service<br/>[audit_service.py]"]
  node_audit_model["Audit records<br/>[audit_log.py]"]
  node_table_service["Storage Tables integration"]
end

subgraph group_operations["Agent and batch operations"]
  node_mcp["MCP tools<br/>[server.py]"]
  node_expiry_job["Expiry scan<br/>[expiry_scan.py]"]
end

node_agent(("LLM agent"))
node_entra["Entra ID"]
node_vault[("Azure Key Vault")]
node_storage_tables[("Azure Storage Tables")]

node_agent -->|"requests tools"| node_mcp
node_mcp -->|"calls API"| node_cert_api
node_mcp -->|"calls API"| node_secret_api
node_api_app -->|"registers route"| node_cert_api
node_api_app -->|"registers route"| node_secret_api
node_api_app -->|"registers route"| node_health_api
node_cert_api -->|"requires JWT"| node_jwt
node_secret_api -.->|"requires JWT"| node_jwt
node_entra -.->|"provides identity"| node_jwt
node_cert_api -->|"calls"| node_cert_service
node_cert_api -->|"logs rotation"| node_audit_service
node_cert_api -->|"loads record"| node_cert_model
node_cert_service -->|"queries and updates"| node_cert_model
node_cert_service -->|"rotates certificate"| node_key_vault
node_key_vault -->|"reads and rotates"| node_vault
node_cert_service -->|"commits metadata"| node_sql
node_audit_service -->|"creates record"| node_audit_model
node_audit_service -->|"appends event"| node_table_service
node_audit_service -->|"commits event"| node_sql
node_table_service -->|"writes event"| node_storage_tables
node_expiry_job -->|"refreshes status"| node_cert_service
node_expiry_job -->|"records summary"| node_audit_service
node_secret_api -.->|"delegates operations"| node_secret_service
node_secret_service -.->|"uses vault"| node_key_vault

click node_mcp "https://github.com/christoph865/certops-agent/blob/main/mcp_server/server.py"
click node_api_app "https://github.com/christoph865/certops-agent/blob/main/app/__init__.py"
click node_cert_api "https://github.com/christoph865/certops-agent/blob/main/app/api/certificates.py"
click node_secret_api "https://github.com/christoph865/certops-agent/blob/main/app/api/secrets.py"
click node_health_api "https://github.com/christoph865/certops-agent/blob/main/app/api/health.py"
click node_jwt "https://github.com/christoph865/certops-agent/blob/main/app/core/extensions.py"
click node_cert_service "https://github.com/christoph865/certops-agent/blob/main/app/services/certificate_service.py"
click node_cert_model "https://github.com/christoph865/certops-agent/blob/main/app/models/certificate.py"
click node_x509 "https://github.com/christoph865/certops-agent/blob/main/app/services/x509_utils.py"
click node_secret_service "https://github.com/christoph865/certops-agent/blob/main/app/services/secret_service.py"
click node_key_vault "https://github.com/christoph865/certops-agent/blob/main/app/services/key_vault_service.py"
click node_audit_service "https://github.com/christoph865/certops-agent/blob/main/app/services/audit_service.py"
click node_audit_model "https://github.com/christoph865/certops-agent/blob/main/app/models/audit_log.py"
click node_table_service "https://github.com/christoph865/certops-agent/blob/main/app/services/storage_table_service.py"
click node_expiry_job "https://github.com/christoph865/certops-agent/blob/main/app/jobs/expiry_scan.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_api_app,node_cert_api,node_secret_api,node_health_api,node_jwt toneBlue
class node_cert_service,node_cert_model,node_x509,node_vault,node_storage_tables toneAmber
class node_secret_service,node_key_vault toneMint
class node_sql,node_audit_service,node_audit_model,node_table_service toneRose
class node_mcp,node_expiry_job,node_agent,node_entra toneIndigo
```

## Components

### API and access

- [Flask application](https://github.com/christoph865/certops-agent/blob/main/app/__init__.py): `app/__init__.py`
- [Certificate API](https://github.com/christoph865/certops-agent/blob/main/app/api/certificates.py): `app/api/certificates.py`
- [Secret API](https://github.com/christoph865/certops-agent/blob/main/app/api/secrets.py): `app/api/secrets.py`
- [Health API](https://github.com/christoph865/certops-agent/blob/main/app/api/health.py): `app/api/health.py`
- [JWT access](https://github.com/christoph865/certops-agent/blob/main/app/core/extensions.py): `app/core/extensions.py`

### Certificate lifecycle

- [Certificate service](https://github.com/christoph865/certops-agent/blob/main/app/services/certificate_service.py): `app/services/certificate_service.py`
- [Certificate metadata](https://github.com/christoph865/certops-agent/blob/main/app/models/certificate.py): `app/models/certificate.py`
- [X.509 utilities](https://github.com/christoph865/certops-agent/blob/main/app/services/x509_utils.py): `app/services/x509_utils.py`

### Secret lifecycle

- [Secret service](https://github.com/christoph865/certops-agent/blob/main/app/services/secret_service.py): `app/services/secret_service.py`
- [Key Vault integration](https://github.com/christoph865/certops-agent/blob/main/app/services/key_vault_service.py): `app/services/key_vault_service.py`

### Persistence and audit

- **SQL database**
- [Audit service](https://github.com/christoph865/certops-agent/blob/main/app/services/audit_service.py): `app/services/audit_service.py`
- [Audit records](https://github.com/christoph865/certops-agent/blob/main/app/models/audit_log.py): `app/models/audit_log.py`
- [Storage Tables integration](https://github.com/christoph865/certops-agent/blob/main/app/services/storage_table_service.py): `app/services/storage_table_service.py`

### Agent and batch operations

- [MCP tools](https://github.com/christoph865/certops-agent/blob/main/mcp_server/server.py): `mcp_server/server.py`
- [Expiry scan](https://github.com/christoph865/certops-agent/blob/main/app/jobs/expiry_scan.py): `app/jobs/expiry_scan.py`

### Other components

- **LLM agent**
- **Entra ID**
- **Azure Key Vault**
- **Azure Storage Tables**

## Connections

- LLM agent → MCP tools: requests tools (evidence: `README.md`)
- MCP tools → Certificate API: calls API (evidence: `README.md`)
- MCP tools → Secret API: calls API (evidence: `README.md`)
- Flask application → Certificate API: registers route (evidence: `app/__init__.py`)
- Flask application → Secret API: registers route (evidence: `app/__init__.py`)
- Flask application → Health API: registers route (evidence: `app/__init__.py`)
- Certificate API → JWT access: requires JWT (evidence: `app/api/certificates.py`)
- Secret API → JWT access: requires JWT
- Entra ID → JWT access: provides identity
- Certificate API → Certificate service: calls (evidence: `app/api/certificates.py`)
- Certificate API → Audit service: logs rotation (evidence: `app/api/certificates.py`)
- Certificate API → Certificate metadata: loads record (evidence: `app/api/certificates.py`)
- Certificate service → Certificate metadata: queries and updates (evidence: `app/services/certificate_service.py`)
- Certificate service → Key Vault integration: rotates certificate (evidence: `app/services/certificate_service.py`)
- Key Vault integration → Azure Key Vault: reads and rotates (evidence: `app/services/key_vault_service.py`)
- Certificate service → SQL database: commits metadata (evidence: `app/services/certificate_service.py`)
- Audit service → Audit records: creates record (evidence: `app/services/audit_service.py`)
- Audit service → Storage Tables integration: appends event (evidence: `app/services/audit_service.py`)
- Audit service → SQL database: commits event (evidence: `app/services/audit_service.py`)
- Storage Tables integration → Azure Storage Tables: writes event (evidence: `app/services/storage_table_service.py`)
- Expiry scan → Certificate service: refreshes status (evidence: `app/jobs/expiry_scan.py`)
- Expiry scan → Audit service: records summary (evidence: `app/jobs/expiry_scan.py`)
- Secret API → Secret service: delegates operations
- Secret service → Key Vault integration: uses vault