# feedutia/portabilize.ai-real architecture

> Architecture diagram of the GitHub repository feedutia/portabilize.ai-real, 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/feedutia/portabilize.ai-real
- Repository: https://github.com/feedutia/portabilize.ai-real

## Overview

Portabilize.ai is a CRM for consignado-credit portability. Its documented operator workflow covers authentication, client and contract data, financial simulation/analysis, and operational tracking; a Python motor separately extracts structured data from uploaded documents. The graph preserves the documented capabilities, but sampled frontend files do not show their API calls, and the excerpts do not establish how the Node routes communicate with the Python motor. Those links are therefore omitted rather than inferred.

Main entry points: [`backend/auth.ts`](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth.ts) (Auth router), [`motor/engine/pipeline.py`](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/pipeline.py) (Extraction pipeline), [`backend/dataRoutes.ts`](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/dataRoutes.ts) (Data and simulation API), [`backend/server.ts`](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/server.ts) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Operator interface"]
  node_app_forms["Client forms<br/>[app-forms.js]"]
  node_app_admin["Admin tools<br/>[app-admin.js]"]
  node_app_tracking["Client tracking<br/>[app-tracking.js]"]
  node_app_motor["Motor UI<br/>[app-motor.js]"]
  node_frontend_finance["Finance calculations<br/>[finance.js]"]
  node_nuclea["Nuclea support<br/>[nuclea.js]"]
end

subgraph group_backend["CRM backend"]
  node_backend_server["HTTP server<br/>[server.ts]"]
  node_data_routes["Data and simulation API<br/>[dataRoutes.ts]"]
  node_attachments["Attachment API"]
  node_motor_routes["Motor API routes<br/>[motorRoutes.ts]"]
  node_financial_engine["Financial validator<br/>[financialEngine.ts]"]
  node_schema["Request validation<br/>[schema.ts]"]
  node_audit["Audit log<br/>[audit.ts]"]
end

subgraph group_identity["Identity and security"]
  node_auth["Auth router<br/>[auth.ts]"]
  node_login_routes["Login and TOTP"]
  node_admin_routes["User administration"]
  node_auth_state["Auth state and limits<br/>[auth-state.ts]"]
  node_auth_cache["User cache<br/>[auth-cache.ts]"]
  node_auth_lockout["Login lockout<br/>[auth-lockout.ts]"]
  node_auth_middleware["Auth middleware<br/>[auth-middleware.ts]"]
  node_crypto["Secret encryption<br/>[crypto-helpers.ts]"]
end

subgraph group_storage["Persistence"]
  node_db_selector["Database selector<br/>[database.ts]"]
  node_local_db[("Local JSON store<br/>[database-local.ts]")]
  node_cosmos_db[("Cosmos store<br/>[database-cosmos.ts]")]
end

subgraph group_motor["Document extraction motor"]
  node_motor_main["Motor entry point<br/>[main.py]"]
  node_crm_adapter["CRM adapter<br/>[adaptador_crm.py]"]
  node_pipeline["Extraction pipeline<br/>[pipeline.py]"]
  node_ingestion["Document ingestion<br/>[leitor_pdf.py]"]
  node_ocr["OCR<br/>[ocr.py]"]
  node_structuring["Text structuring<br/>[estruturador.py]"]
  node_classification["Document classification<br/>[classificador.py]"]
  node_template_extract["Template extraction"]
  node_llm_extract["LLM extraction fallback<br/>[extrator_llm.py]"]
end

node_operator(("Operator"))

node_operator -->|"enters client workflow"| node_app_forms
node_operator -->|"uses administration"| node_app_admin
node_operator -->|"tracks clients"| node_app_tracking
node_operator -->|"uses document motor"| node_app_motor
node_frontend_finance -->|"server rechecks calculations"| node_financial_engine
node_backend_server -->|"mounts routes"| node_auth
node_backend_server -->|"mounts routes"| node_data_routes
node_backend_server -->|"mounts routes"| node_attachments
node_backend_server -->|"mounts routes"| node_motor_routes
node_data_routes -->|"reads and writes"| node_db_selector
node_data_routes -->|"runs simulation"| node_financial_engine
node_data_routes -->|"validates requests"| node_schema
node_data_routes -->|"records events"| node_audit
node_attachments -->|"uses authentication"| node_auth
node_motor_routes -->|"uses authentication"| node_auth
node_auth -->|"mounts router"| node_login_routes
node_auth -->|"mounts router"| node_admin_routes
node_auth -->|"uses shared state"| node_auth_state
node_auth -->|"initializes cache"| node_auth_cache
node_auth -->|"exports guards"| node_auth_middleware
node_login_routes -->|"uses user state"| node_auth_state
node_login_routes -->|"updates failure limits"| node_auth_lockout
node_login_routes -->|"records login events"| node_audit
node_admin_routes -->|"refreshes user cache"| node_auth_cache
node_admin_routes -->|"records admin events"| node_audit
node_auth_state -->|"decrypts cached secrets"| node_crypto
node_db_selector -->|"selects when configured"| node_cosmos_db
node_db_selector -->|"selects by default"| node_local_db
node_motor_main -->|"invokes pipeline"| node_pipeline
node_motor_main -->|"uses adapter"| node_crm_adapter
node_pipeline -->|"reads documents"| node_ingestion
node_pipeline -->|"runs OCR"| node_ocr
node_pipeline -->|"structures text"| node_structuring
node_pipeline -->|"classifies document"| node_classification
node_pipeline -->|"tries templates"| node_template_extract
node_pipeline -->|"falls back to LLM"| node_llm_extract

click node_app_forms "https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/modules/app-forms.js"
click node_app_admin "https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/modules/app-admin.js"
click node_app_tracking "https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/modules/app-tracking.js"
click node_app_motor "https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/modules/app-motor.js"
click node_frontend_finance "https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/finance.js"
click node_nuclea "https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/nuclea.js"
click node_backend_server "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/server.ts"
click node_data_routes "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/dataRoutes.ts"
click node_attachments "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/attachmentRoutes.ts"
click node_motor_routes "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/motorRoutes.ts"
click node_financial_engine "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/financialEngine.ts"
click node_schema "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/schema.ts"
click node_audit "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/audit.ts"
click node_auth "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth.ts"
click node_login_routes "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-routes-login.ts"
click node_admin_routes "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-routes-admin.ts"
click node_auth_state "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-state.ts"
click node_auth_cache "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-cache.ts"
click node_auth_lockout "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-lockout.ts"
click node_auth_middleware "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-middleware.ts"
click node_crypto "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/crypto-helpers.ts"
click node_db_selector "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/database.ts"
click node_local_db "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/database-local.ts"
click node_cosmos_db "https://github.com/feedutia/portabilize.ai-real/blob/main/backend/database-cosmos.ts"
click node_motor_main "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/main.py"
click node_crm_adapter "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/adaptador_crm.py"
click node_pipeline "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/pipeline.py"
click node_ingestion "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada1_ingestao/leitor_pdf.py"
click node_ocr "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada1_ingestao/ocr.py"
click node_structuring "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada1_ingestao/estruturador.py"
click node_classification "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada2_classificacao/classificador.py"
click node_template_extract "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada3_extracao/extrator_template.py"
click node_llm_extract "https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada3_extracao/extrator_llm.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_app_forms,node_app_admin,node_app_tracking,node_app_motor,node_frontend_finance,node_nuclea toneBlue
class node_backend_server,node_data_routes,node_attachments,node_motor_routes,node_financial_engine,node_schema,node_audit toneAmber
class node_auth,node_login_routes,node_admin_routes,node_auth_state,node_auth_cache,node_auth_lockout,node_auth_middleware,node_crypto toneMint
class node_db_selector,node_local_db,node_cosmos_db toneRose
class node_motor_main,node_crm_adapter,node_pipeline,node_ingestion,node_ocr,node_structuring,node_classification,node_template_extract,node_llm_extract,node_operator toneIndigo
```

## Components

### Operator interface

- [Client forms](https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/modules/app-forms.js): `frontend/js/modules/app-forms.js`
- [Admin tools](https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/modules/app-admin.js): `frontend/js/modules/app-admin.js`
- [Client tracking](https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/modules/app-tracking.js): `frontend/js/modules/app-tracking.js`
- [Motor UI](https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/modules/app-motor.js): `frontend/js/modules/app-motor.js`
- [Finance calculations](https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/finance.js): `frontend/js/finance.js`
- [Nuclea support](https://github.com/feedutia/portabilize.ai-real/blob/main/frontend/js/nuclea.js): `frontend/js/nuclea.js`

### CRM backend

- [HTTP server](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/server.ts): `backend/server.ts`
- [Data and simulation API](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/dataRoutes.ts): `backend/dataRoutes.ts`
- [Attachment API](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/attachmentRoutes.ts): `backend/attachmentRoutes.ts`
- [Motor API routes](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/motorRoutes.ts): `backend/motorRoutes.ts`
- [Financial validator](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/financialEngine.ts): `backend/financialEngine.ts`
- [Request validation](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/schema.ts): `backend/schema.ts`
- [Audit log](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/audit.ts): `backend/audit.ts`

### Identity and security

- [Auth router](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth.ts): `backend/auth.ts`
- [Login and TOTP](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-routes-login.ts): `backend/auth-routes-login.ts`
- [User administration](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-routes-admin.ts): `backend/auth-routes-admin.ts`
- [Auth state and limits](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-state.ts): `backend/auth-state.ts`
- [User cache](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-cache.ts): `backend/auth-cache.ts`
- [Login lockout](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-lockout.ts): `backend/auth-lockout.ts`
- [Auth middleware](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/auth-middleware.ts): `backend/auth-middleware.ts`
- [Secret encryption](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/crypto-helpers.ts): `backend/crypto-helpers.ts`

### Persistence

- [Database selector](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/database.ts): `backend/database.ts`
- [Local JSON store](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/database-local.ts): `backend/database-local.ts`
- [Cosmos store](https://github.com/feedutia/portabilize.ai-real/blob/main/backend/database-cosmos.ts): `backend/database-cosmos.ts`

### Document extraction motor

- [Motor entry point](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/main.py): `motor/main.py`
- [CRM adapter](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/adaptador_crm.py): `motor/engine/adaptador_crm.py`
- [Extraction pipeline](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/pipeline.py): `motor/engine/pipeline.py`
- [Document ingestion](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada1_ingestao/leitor_pdf.py): `motor/engine/camada1_ingestao/leitor_pdf.py`
- [OCR](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada1_ingestao/ocr.py): `motor/engine/camada1_ingestao/ocr.py`
- [Text structuring](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada1_ingestao/estruturador.py): `motor/engine/camada1_ingestao/estruturador.py`
- [Document classification](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada2_classificacao/classificador.py): `motor/engine/camada2_classificacao/classificador.py`
- [Template extraction](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada3_extracao/extrator_template.py): `motor/engine/camada3_extracao/extrator_template.py`
- [LLM extraction fallback](https://github.com/feedutia/portabilize.ai-real/blob/main/motor/engine/camada3_extracao/extrator_llm.py): `motor/engine/camada3_extracao/extrator_llm.py`

### Other components

- **Operator**

## Connections

- Operator → Client forms: enters client workflow
- Operator → Admin tools: uses administration
- Operator → Client tracking: tracks clients
- Operator → Motor UI: uses document motor
- Finance calculations → Financial validator: server rechecks calculations (evidence: `backend/financialEngine.ts`)
- HTTP server → Auth router: mounts routes (evidence: `backend/server.ts`)
- HTTP server → Data and simulation API: mounts routes (evidence: `backend/server.ts`)
- HTTP server → Attachment API: mounts routes (evidence: `backend/server.ts`)
- HTTP server → Motor API routes: mounts routes (evidence: `backend/server.ts`)
- Data and simulation API → Database selector: reads and writes (evidence: `backend/dataRoutes.ts`)
- Data and simulation API → Financial validator: runs simulation (evidence: `backend/dataRoutes.ts`)
- Data and simulation API → Request validation: validates requests (evidence: `backend/dataRoutes.ts`)
- Data and simulation API → Audit log: records events (evidence: `backend/dataRoutes.ts`)
- Attachment API → Auth router: uses authentication (evidence: `backend/attachmentRoutes.ts`)
- Motor API routes → Auth router: uses authentication (evidence: `backend/motorRoutes.ts`)
- Auth router → Login and TOTP: mounts router (evidence: `backend/auth.ts`)
- Auth router → User administration: mounts router (evidence: `backend/auth.ts`)
- Auth router → Auth state and limits: uses shared state (evidence: `backend/auth.ts`)
- Auth router → User cache: initializes cache (evidence: `backend/auth.ts`)
- Auth router → Auth middleware: exports guards (evidence: `backend/auth.ts`)
- Login and TOTP → Auth state and limits: uses user state (evidence: `backend/auth-routes-login.ts`)
- Login and TOTP → Login lockout: updates failure limits (evidence: `backend/auth-routes-login.ts`)
- Login and TOTP → Audit log: records login events (evidence: `backend/auth-routes-login.ts`)
- User administration → User cache: refreshes user cache (evidence: `backend/auth-routes-admin.ts`)
- User administration → Audit log: records admin events (evidence: `backend/auth-routes-admin.ts`)
- Auth state and limits → Secret encryption: decrypts cached secrets (evidence: `backend/auth-state.ts`)
- Database selector → Cosmos store: selects when configured (evidence: `backend/database.ts`)
- Database selector → Local JSON store: selects by default (evidence: `backend/database.ts`)
- Motor entry point → Extraction pipeline: invokes pipeline (evidence: `motor/main.py`)
- Motor entry point → CRM adapter: uses adapter (evidence: `motor/main.py`)
- Extraction pipeline → Document ingestion: reads documents (evidence: `motor/engine/pipeline.py`)
- Extraction pipeline → OCR: runs OCR (evidence: `motor/engine/pipeline.py`)
- Extraction pipeline → Text structuring: structures text (evidence: `motor/engine/pipeline.py`)
- Extraction pipeline → Document classification: classifies document (evidence: `motor/engine/pipeline.py`)
- Extraction pipeline → Template extraction: tries templates (evidence: `motor/engine/pipeline.py`)
- Extraction pipeline → LLM extraction fallback: falls back to LLM (evidence: `motor/engine/pipeline.py`)
