# ciroligeiro/assineaqui architecture

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

- Interactive diagram: https://gitdiagram.com/ciroligeiro/assineaqui
- Repository: https://github.com/ciroligeiro/assineaqui

## Overview

Assine Aqui is a web platform for business-document signing, with mandatory MFA, role-based administration, an internal certificate authority, and HSM-isolated signing keys. The main workflow is users authenticating, managing or uploading documents, assigning signers, signing, and verifying signatures; administrators can also review audit and signature records. The graph includes documented encrypted MinIO storage and shared rate limiting. Edges rely on the excerpts, SOURCE INDEX references, or README statements; unsampled implementation details and unshown frontend-to-route mappings are omitted.

Main entry points: [`backend/models/database.py`](https://github.com/ciroligeiro/assineaqui/blob/main/backend/models/database.py) (Relational records), [`backend/app.py`](https://github.com/ciroligeiro/assineaqui/blob/main/backend/app.py) (Flask app), [`backend/routes/signatures.py`](https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/signatures.py) (Signature workflow), [`backend/routes/documents.py`](https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/documents.py) (Document workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_frontend["Web dashboards"]
end

subgraph group_api["Application API"]
  node_app["Flask app<br/>[app.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_mfa["MFA<br/>[mfa.py]"]
  node_users["User management<br/>[users.py]"]
  node_documents["Document workflow<br/>[documents.py]"]
  node_signatures["Signature workflow<br/>[signatures.py]"]
  node_audit_routes["Audit queries<br/>[audit.py]"]
end

subgraph group_signing["Signing and cryptography"]
  node_encryption["Document encryption"]
  node_pdf_stamp["PDF stamping<br/>[pdf_stamp.py]"]
  node_rsa["RSA-PSS signatures<br/>[rsa_signature.py]"]
  node_pki["Certificate authority<br/>[pki.py]"]
end

subgraph group_data["Persistence and audit"]
  node_database[("Relational records<br/>[database.py]")]
  node_audit["Audit writer<br/>[audit.py]"]
  node_storage["Encrypted object storage<br/>[storage.py]"]
end

subgraph group_security["Security infrastructure"]
  node_permissions["Role checks<br/>[permissions.py]"]
  node_hsm["PKCS&#35;11 key store<br/>[hsm.py]"]
  node_limiter["Shared rate limiter<br/>[extensions.py]"]
end

node_user(("Platform user"))
node_minio[("MinIO")]
node_postgres[("PostgreSQL")]
node_redis[("Redis")]

node_user -->|"uses"| node_frontend
node_frontend -->|"fetches API"| node_app
node_app -->|"mounts routes"| node_auth
node_app -->|"mounts routes"| node_users
node_app -->|"mounts routes"| node_documents
node_app -->|"mounts routes"| node_signatures
node_app -->|"mounts routes"| node_mfa
node_app -->|"mounts routes"| node_audit_routes
node_app -->|"attaches"| node_limiter
node_auth -->|"reads users"| node_database
node_auth -->|"decrypts MFA secret"| node_encryption
node_auth -->|"records events"| node_audit
node_mfa -->|"reads MFA state"| node_database
node_mfa -->|"handles MFA secret"| node_encryption
node_users -->|"manages accounts"| node_database
node_users -->|"creates user keys"| node_hsm
node_users -->|"issues certificates"| node_pki
node_documents -->|"manages records"| node_database
node_documents -->|"encrypts documents"| node_encryption
node_documents -->|"stores documents"| node_storage
node_documents -->|"stamps PDFs"| node_pdf_stamp
node_documents -->|"records events"| node_audit
node_documents -->|"checks access"| node_permissions
node_signatures -->|"manages signatures"| node_database
node_signatures -->|"decrypts documents"| node_encryption
node_signatures -->|"signs and verifies"| node_rsa
node_signatures -->|"verifies certificates"| node_pki
node_signatures -->|"retrieves documents"| node_storage
node_signatures -->|"records events"| node_audit
node_signatures -->|"checks access"| node_permissions
node_audit_routes -->|"reads audit records"| node_database
node_audit_routes -->|"checks access"| node_permissions
node_audit -->|"writes events"| node_database
node_database -->|"generates owner keys"| node_hsm
node_database -->|"issues owner certificate"| node_pki
node_storage -->|"stores objects"| node_minio
node_limiter -->|"shares counters"| node_redis
node_database -->|"persists records"| node_postgres

click node_frontend "https://github.com/ciroligeiro/assineaqui/tree/main/frontend"
click node_app "https://github.com/ciroligeiro/assineaqui/blob/main/backend/app.py"
click node_auth "https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/auth.py"
click node_mfa "https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/mfa.py"
click node_users "https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/users.py"
click node_documents "https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/documents.py"
click node_signatures "https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/signatures.py"
click node_audit_routes "https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/audit.py"
click node_permissions "https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/permissions.py"
click node_database "https://github.com/ciroligeiro/assineaqui/blob/main/backend/models/database.py"
click node_audit "https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/audit.py"
click node_encryption "https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/crypto/aesgcm_encryption.py"
click node_pdf_stamp "https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/pdf_stamp.py"
click node_rsa "https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/crypto/rsa_signature.py"
click node_pki "https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/crypto/pki.py"
click node_hsm "https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/crypto/hsm.py"
click node_storage "https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/storage.py"
click node_limiter "https://github.com/ciroligeiro/assineaqui/blob/main/backend/extensions.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_frontend,node_user toneBlue
class node_app,node_auth,node_mfa,node_users,node_documents,node_signatures,node_audit_routes,node_minio,node_postgres,node_redis toneAmber
class node_encryption,node_pdf_stamp,node_rsa,node_pki toneMint
class node_database,node_audit,node_storage toneRose
class node_permissions,node_hsm,node_limiter toneIndigo
```

## Components

### Web interface

- [Web dashboards](https://github.com/ciroligeiro/assineaqui/tree/main/frontend): `frontend`

### Application API

- [Flask app](https://github.com/ciroligeiro/assineaqui/blob/main/backend/app.py): `backend/app.py`
- [Authentication](https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [MFA](https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/mfa.py): `backend/routes/mfa.py`
- [User management](https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/users.py): `backend/routes/users.py`
- [Document workflow](https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/documents.py): `backend/routes/documents.py`
- [Signature workflow](https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/signatures.py): `backend/routes/signatures.py`
- [Audit queries](https://github.com/ciroligeiro/assineaqui/blob/main/backend/routes/audit.py): `backend/routes/audit.py`

### Signing and cryptography

- [Document encryption](https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/crypto/aesgcm_encryption.py): `backend/tools/crypto/aesgcm_encryption.py`
- [PDF stamping](https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/pdf_stamp.py): `backend/tools/pdf_stamp.py`
- [RSA-PSS signatures](https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/crypto/rsa_signature.py): `backend/tools/crypto/rsa_signature.py`
- [Certificate authority](https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/crypto/pki.py): `backend/tools/crypto/pki.py`

### Persistence and audit

- [Relational records](https://github.com/ciroligeiro/assineaqui/blob/main/backend/models/database.py): `backend/models/database.py`
- [Audit writer](https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/audit.py): `backend/tools/audit.py`
- [Encrypted object storage](https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/storage.py): `backend/tools/storage.py`

### Security infrastructure

- [Role checks](https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/permissions.py): `backend/tools/permissions.py`
- [PKCS#11 key store](https://github.com/ciroligeiro/assineaqui/blob/main/backend/tools/crypto/hsm.py): `backend/tools/crypto/hsm.py`
- [Shared rate limiter](https://github.com/ciroligeiro/assineaqui/blob/main/backend/extensions.py): `backend/extensions.py`

### Other components

- **Platform user**
- **MinIO**
- **PostgreSQL**
- **Redis**

## Connections

- Platform user → Web dashboards: uses (evidence: `README.md`)
- Web dashboards → Flask app: fetches API (evidence: `README.md`)
- Flask app → Authentication: mounts routes (evidence: `backend/app.py`)
- Flask app → User management: mounts routes (evidence: `backend/app.py`)
- Flask app → Document workflow: mounts routes (evidence: `backend/app.py`)
- Flask app → Signature workflow: mounts routes (evidence: `backend/app.py`)
- Flask app → MFA: mounts routes (evidence: `backend/app.py`)
- Flask app → Audit queries: mounts routes (evidence: `backend/app.py`)
- Flask app → Shared rate limiter: attaches (evidence: `backend/app.py`)
- Authentication → Relational records: reads users (evidence: `backend/routes/auth.py`)
- Authentication → Document encryption: decrypts MFA secret (evidence: `backend/routes/auth.py`)
- Authentication → Audit writer: records events (evidence: `backend/routes/auth.py`)
- MFA → Relational records: reads MFA state (evidence: `backend/routes/mfa.py`)
- MFA → Document encryption: handles MFA secret (evidence: `backend/routes/mfa.py`)
- User management → Relational records: manages accounts (evidence: `backend/routes/users.py`)
- User management → PKCS#11 key store: creates user keys (evidence: `backend/routes/users.py`)
- User management → Certificate authority: issues certificates (evidence: `backend/routes/users.py`)
- Document workflow → Relational records: manages records (evidence: `backend/routes/documents.py`)
- Document workflow → Document encryption: encrypts documents (evidence: `backend/routes/documents.py`)
- Document workflow → Encrypted object storage: stores documents (evidence: `backend/routes/documents.py`)
- Document workflow → PDF stamping: stamps PDFs (evidence: `backend/routes/documents.py`)
- Document workflow → Audit writer: records events (evidence: `backend/routes/documents.py`)
- Document workflow → Role checks: checks access (evidence: `backend/routes/documents.py`)
- Signature workflow → Relational records: manages signatures (evidence: `backend/routes/signatures.py`)
- Signature workflow → Document encryption: decrypts documents (evidence: `backend/routes/signatures.py`)
- Signature workflow → RSA-PSS signatures: signs and verifies (evidence: `backend/routes/signatures.py`)
- Signature workflow → Certificate authority: verifies certificates (evidence: `backend/routes/signatures.py`)
- Signature workflow → Encrypted object storage: retrieves documents (evidence: `backend/routes/signatures.py`)
- Signature workflow → Audit writer: records events (evidence: `backend/routes/signatures.py`)
- Signature workflow → Role checks: checks access (evidence: `backend/routes/signatures.py`)
- Audit queries → Relational records: reads audit records (evidence: `backend/routes/audit.py`)
- Audit queries → Role checks: checks access (evidence: `backend/routes/audit.py`)
- Audit writer → Relational records: writes events (evidence: `backend/tools/audit.py`)
- Relational records → PKCS#11 key store: generates owner keys (evidence: `backend/models/database.py`)
- Relational records → Certificate authority: issues owner certificate (evidence: `backend/models/database.py`)
- Encrypted object storage → MinIO: stores objects (evidence: `backend/tools/storage.py`)
- Shared rate limiter → Redis: shares counters (evidence: `backend/extensions.py`)
- Relational records → PostgreSQL: persists records (evidence: `README.md`)
