# gutembergferreira/oraculo-icms architecture

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

- Interactive diagram: https://gitdiagram.com/gutembergferreira/oraculo-icms
- Repository: https://github.com/gutembergferreira/oraculo-icms

## Overview

Oráculo ICMS is a multi-tenant SaaS for ingesting NF-e XMLs, auditing tax compliance, and managing subscriptions and rule sets. The main workflow runs from the web UI through the API and asynchronous workers: ingest and parse documents, evaluate organization-specific rules, persist findings, then expose summaries and downloadable reports. The graph also preserves authentication, billing, administration, public API, and SSO capabilities documented in the README. Some route and service internals were not excerpted, so those links rely on README statements or are omitted where wiring is uncertain.

Main entry points: [`backend/app/api/v1/routes/__init__.py`](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/api/v1/routes/__init__.py) (HTTP API), [`frontend/src/routes/App.tsx`](https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/routes/App.tsx) (Web app routes), [`backend/app/workers/tasks.py`](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/workers/tasks.py) (Async task worker), [`backend/app/db/session.py`](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/db/session.py) (Application database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Web app routes<br/>[App.tsx]"]
  node_authui["Authentication UI<br/>[AuthContext.tsx]"]
  node_invoiceui["Invoice workspace<br/>[InvoicesPage.tsx]"]
  node_auditui["Audit workspace<br/>[AuditPage.tsx]"]
  node_rulesui["Rules editor<br/>[RulesPage.tsx]"]
  node_billingui["Billing workspace<br/>[BillingPage.tsx]"]
end

subgraph group_api["API and identity"]
  node_api["HTTP API<br/>[__init__.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_admin["Admin and organization routes"]
  node_publicapi["Public API routes<br/>[public_api.py]"]
end

subgraph group_audit["Ingestion and audit"]
  node_workers["Async task worker<br/>[tasks.py]"]
  node_ingestor["Invoice ingestion"]
  node_xmlparser["NF-e XML parser<br/>[xml_parser.py]"]
  node_storage["File storage"]
  node_auditcalc["Audit calculator<br/>[zfm_calculator.py]"]
  node_rulesets["Rule-set service<br/>[ruleset_service.py]"]
  node_ruleengine["DSL rule engine<br/>[rules_engine.py]"]
  node_summary["Audit summaries<br/>[audit_summary.py]"]
  node_reports["Audit reports<br/>[audit_report.py]"]
end

subgraph group_platform["Plans and integrations"]
  node_database[("Application database<br/>[session.py]")]
  node_limits["Organization plan limits<br/>[org_plan_limits.py]"]
  node_plans["Plan catalog<br/>[plan_catalog.py]"]
  node_billing["Stripe billing<br/>[stripe_billing.py]"]
end

node_user(("User"))
node_stripe["Stripe"]
node_sso["SSO provider"]

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_invoiceui
node_webapp -->|"routes to"| node_auditui
node_webapp -->|"routes to"| node_rulesui
node_webapp -->|"routes to"| node_billingui
node_webapp -->|"provides context"| node_authui
node_authui -->|"requests profile"| node_auth
node_invoiceui -->|"uploads and queries"| node_api
node_auditui -->|"queries audits"| node_api
node_rulesui -->|"edits rules"| node_api
node_billingui -->|"requests billing"| node_api
node_api -->|"dispatches routes"| node_auth
node_api -->|"dispatches routes"| node_admin
node_api -->|"dispatches routes"| node_publicapi
node_api -.->|"queues audit jobs"| node_workers
node_workers -->|"ingests batches"| node_ingestor
node_ingestor -->|"parses XML"| node_xmlparser
node_ingestor -->|"stores files"| node_storage
node_ingestor -->|"persists invoices"| node_database
node_workers -->|"runs audits"| node_auditcalc
node_auditcalc -->|"loads rules"| node_rulesets
node_auditcalc -->|"evaluates DSL"| node_ruleengine
node_workers -->|"checks usage"| node_limits
node_workers -->|"builds summaries"| node_summary
node_workers -->|"generates reports"| node_reports
node_auditcalc -->|"persists findings"| node_database
node_summary -.->|"reads audit data"| node_database
node_reports -.->|"reads audit data"| node_database
node_api -.->|"serves plan catalog"| node_plans
node_billing -->|"uses catalog"| node_plans
node_billing -->|"creates subscriptions"| node_stripe
node_billing -->|"updates subscriptions"| node_database
node_limits -->|"tracks usage"| node_database
node_auth -->|"authenticates optionally"| node_sso
node_auth -->|"reads and writes users"| node_database

click node_webapp "https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/routes/App.tsx"
click node_authui "https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/contexts/AuthContext.tsx"
click node_invoiceui "https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/pages/InvoicesPage.tsx"
click node_auditui "https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/pages/AuditPage.tsx"
click node_rulesui "https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/pages/RulesPage.tsx"
click node_billingui "https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/pages/BillingPage.tsx"
click node_api "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/api/v1/routes/__init__.py"
click node_auth "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/api/v1/routes/auth.py"
click node_admin "https://github.com/gutembergferreira/oraculo-icms/tree/master/backend/app/api/v1/routes"
click node_publicapi "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/api/v1/routes/public_api.py"
click node_workers "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/workers/tasks.py"
click node_ingestor "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/invoice_ingestion.py"
click node_xmlparser "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/utils/xml_parser.py"
click node_storage "https://github.com/gutembergferreira/oraculo-icms/tree/master/backend/app/services/storage"
click node_auditcalc "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/zfm_calculator.py"
click node_rulesets "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/ruleset_service.py"
click node_ruleengine "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/rules_engine.py"
click node_summary "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/audit_summary.py"
click node_reports "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/audit_report.py"
click node_database "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/db/session.py"
click node_limits "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/org_plan_limits.py"
click node_plans "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/plan_catalog.py"
click node_billing "https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/stripe_billing.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_webapp,node_authui,node_invoiceui,node_auditui,node_rulesui,node_billingui,node_user toneBlue
class node_api,node_auth,node_admin,node_publicapi toneAmber
class node_workers,node_ingestor,node_xmlparser,node_storage,node_auditcalc,node_rulesets,node_ruleengine,node_summary,node_reports toneMint
class node_database,node_limits,node_plans,node_billing toneRose
class node_stripe,node_sso toneIndigo
```

## Components

### Web application

- [Web app routes](https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/routes/App.tsx): `frontend/src/routes/App.tsx`
- [Authentication UI](https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [Invoice workspace](https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/pages/InvoicesPage.tsx): `frontend/src/pages/InvoicesPage.tsx`
- [Audit workspace](https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/pages/AuditPage.tsx): `frontend/src/pages/AuditPage.tsx`
- [Rules editor](https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/pages/RulesPage.tsx): `frontend/src/pages/RulesPage.tsx`
- [Billing workspace](https://github.com/gutembergferreira/oraculo-icms/blob/master/frontend/src/pages/BillingPage.tsx): `frontend/src/pages/BillingPage.tsx`

### API and identity

- [HTTP API](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/api/v1/routes/__init__.py): `backend/app/api/v1/routes/__init__.py`
- [Authentication routes](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/api/v1/routes/auth.py): `backend/app/api/v1/routes/auth.py`
- [Admin and organization routes](https://github.com/gutembergferreira/oraculo-icms/tree/master/backend/app/api/v1/routes): `backend/app/api/v1/routes`
- [Public API routes](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/api/v1/routes/public_api.py): `backend/app/api/v1/routes/public_api.py`

### Ingestion and audit

- [Async task worker](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/workers/tasks.py): `backend/app/workers/tasks.py`
- [Invoice ingestion](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/invoice_ingestion.py): `backend/app/services/invoice_ingestion.py`
- [NF-e XML parser](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/utils/xml_parser.py): `backend/app/utils/xml_parser.py`
- [File storage](https://github.com/gutembergferreira/oraculo-icms/tree/master/backend/app/services/storage): `backend/app/services/storage`
- [Audit calculator](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/zfm_calculator.py): `backend/app/services/zfm_calculator.py`
- [Rule-set service](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/ruleset_service.py): `backend/app/services/ruleset_service.py`
- [DSL rule engine](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/rules_engine.py): `backend/app/services/rules_engine.py`
- [Audit summaries](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/audit_summary.py): `backend/app/services/audit_summary.py`
- [Audit reports](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/audit_report.py): `backend/app/services/audit_report.py`

### Plans and integrations

- [Application database](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/db/session.py): `backend/app/db/session.py`
- [Organization plan limits](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/org_plan_limits.py): `backend/app/services/org_plan_limits.py`
- [Plan catalog](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/plan_catalog.py): `backend/app/services/plan_catalog.py`
- [Stripe billing](https://github.com/gutembergferreira/oraculo-icms/blob/master/backend/app/services/stripe_billing.py): `backend/app/services/stripe_billing.py`

### Other components

- **User**
- **Stripe**
- **SSO provider**

## Connections

- User → Web app routes: uses (evidence: `frontend/src/routes/App.tsx`)
- Web app routes → Invoice workspace: routes to (evidence: `frontend/src/routes/App.tsx`)
- Web app routes → Audit workspace: routes to (evidence: `frontend/src/routes/App.tsx`)
- Web app routes → Rules editor: routes to (evidence: `frontend/src/routes/App.tsx`)
- Web app routes → Billing workspace: routes to (evidence: `frontend/src/routes/App.tsx`)
- Web app routes → Authentication UI: provides context (evidence: `frontend/src/main.tsx`)
- Authentication UI → Authentication routes: requests profile (evidence: `frontend/src/contexts/AuthContext.tsx`)
- Invoice workspace → HTTP API: uploads and queries
- Audit workspace → HTTP API: queries audits
- Rules editor → HTTP API: edits rules
- Billing workspace → HTTP API: requests billing
- HTTP API → Authentication routes: dispatches routes (evidence: `backend/app/api/v1/routes/__init__.py`)
- HTTP API → Admin and organization routes: dispatches routes (evidence: `backend/app/api/v1/routes/__init__.py`)
- HTTP API → Public API routes: dispatches routes (evidence: `backend/app/api/v1/routes/__init__.py`)
- HTTP API → Async task worker: queues audit jobs
- Async task worker → Invoice ingestion: ingests batches (evidence: `backend/app/workers/tasks.py`)
- Invoice ingestion → NF-e XML parser: parses XML (evidence: `backend/app/services/invoice_ingestion.py`)
- Invoice ingestion → File storage: stores files (evidence: `backend/app/services/invoice_ingestion.py`)
- Invoice ingestion → Application database: persists invoices (evidence: `backend/app/services/invoice_ingestion.py`)
- Async task worker → Audit calculator: runs audits (evidence: `backend/app/workers/tasks.py`)
- Audit calculator → Rule-set service: loads rules
- Audit calculator → DSL rule engine: evaluates DSL
- Async task worker → Organization plan limits: checks usage (evidence: `backend/app/workers/tasks.py`)
- Async task worker → Audit summaries: builds summaries (evidence: `backend/app/workers/tasks.py`)
- Async task worker → Audit reports: generates reports (evidence: `backend/app/workers/tasks.py`)
- Audit calculator → Application database: persists findings
- Audit summaries → Application database: reads audit data
- Audit reports → Application database: reads audit data
- HTTP API → Plan catalog: serves plan catalog
- Stripe billing → Plan catalog: uses catalog
- Stripe billing → Stripe: creates subscriptions
- Stripe billing → Application database: updates subscriptions
- Organization plan limits → Application database: tracks usage
- Authentication routes → SSO provider: authenticates optionally (evidence: `backend/app/api/v1/routes/auth.py`)
- Authentication routes → Application database: reads and writes users (evidence: `backend/app/api/v1/routes/auth.py`)