How gutembergferreira/oraculo-icms works
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: __init__.py HTTP API · App.tsx Web app routes · tasks.py Async task worker · session.py Application database
Components 26
Web application
- Web app routes
frontend/src/routes/App.tsx - Authentication UI
frontend/src/contexts/AuthContext.tsx - Invoice workspace
frontend/src/pages/InvoicesPage.tsx - Audit workspace
frontend/src/pages/AuditPage.tsx - Rules editor
frontend/src/pages/RulesPage.tsx - Billing workspace
frontend/src/pages/BillingPage.tsx
API and identity
- HTTP API
backend/app/api/v1/routes/__init__.py - Authentication routes
backend/app/api/v1/routes/auth.py - Admin and organization routes
backend/app/api/v1/routes - Public API routes
backend/app/api/v1/routes/public_api.py
Ingestion and audit
- Async task worker
backend/app/workers/tasks.py - Invoice ingestion
backend/app/services/invoice_ingestion.py - NF-e XML parser
backend/app/utils/xml_parser.py - File storage
backend/app/services/storage - Audit calculator
backend/app/services/zfm_calculator.py - Rule-set service
backend/app/services/ruleset_service.py - DSL rule engine
backend/app/services/rules_engine.py - Audit summaries
backend/app/services/audit_summary.py - Audit reports
backend/app/services/audit_report.py
Plans and integrations
- Application database
backend/app/db/session.py - Organization plan limits
backend/app/services/org_plan_limits.py - Plan catalog
backend/app/services/plan_catalog.py - Stripe billing
backend/app/services/stripe_billing.py
Other components
- User
- Stripe
- SSO provider
Connections 35
- User → Web app routes: uses
frontend/src/routes/App.tsx - Web app routes → Invoice workspace: routes to
frontend/src/routes/App.tsx - Web app routes → Audit workspace: routes to
frontend/src/routes/App.tsx - Web app routes → Rules editor: routes to
frontend/src/routes/App.tsx - Web app routes → Billing workspace: routes to
frontend/src/routes/App.tsx - Web app routes → Authentication UI: provides context
frontend/src/main.tsx - Authentication UI → Authentication routes: requests profile
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
backend/app/api/v1/routes/__init__.py - HTTP API → Admin and organization routes: dispatches routes
backend/app/api/v1/routes/__init__.py - HTTP API → Public API routes: dispatches routes
backend/app/api/v1/routes/__init__.py - HTTP API → Async task worker: queues audit jobs
- Async task worker → Invoice ingestion: ingests batches
backend/app/workers/tasks.py - Invoice ingestion → NF-e XML parser: parses XML
backend/app/services/invoice_ingestion.py - Invoice ingestion → File storage: stores files
backend/app/services/invoice_ingestion.py - Invoice ingestion → Application database: persists invoices
backend/app/services/invoice_ingestion.py - Async task worker → Audit calculator: runs audits
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
backend/app/workers/tasks.py - Async task worker → Audit summaries: builds summaries
backend/app/workers/tasks.py - Async task worker → Audit reports: generates reports
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
backend/app/api/v1/routes/auth.py - Authentication routes → Application database: reads and writes users
backend/app/api/v1/routes/auth.py