# marcelogcardozo/processa-ai architecture

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

- Interactive diagram: https://gitdiagram.com/marcelogcardozo/processa-ai
- Repository: https://github.com/marcelogcardozo/processa-ai

## Overview

Processa AI was a legal-practice SaaS combining office management, a client portal, billing, AI tools, legal chat, and calculators. The main workflow runs from a user-facing React app through the FastAPI backend; queued analysis and document work is handled by a separate worker, with results and records stored in PostgreSQL/Supabase. The README documents the product capabilities and service split; edges are limited to relationships supported by it or by the supplied source index and excerpts. Some feature internals were not sampled, so their connections are omitted.

Main entry points: [`apps/backend/src/main.py`](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/main.py) (FastAPI service), [`services/worker/src/main.py`](https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/main.py) (Job worker), [`apps/frontend/src/App.tsx`](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/frontend/src/App.tsx) (React application), [`apps/backend/src/core/job_store.py`](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/core/job_store.py) (Job store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["User applications"]
  node_frontend["React application<br/>[App.tsx]"]
  node_auth["Authentication<br/>[auth-service.ts]"]
  node_office["Office management"]
  node_portal["Client portal<br/>[service.py]"]
  node_blog["Blog and materials<br/>[service.py]"]
end

subgraph group_backend["Backend services"]
  node_backend_api["FastAPI service<br/>[main.py]"]
  node_profiles["Profiles and dashboard<br/>[service.py]"]
  node_billing["Billing and credits<br/>[service.py]"]
  node_job_store["Job store<br/>[job_store.py]"]
  node_db_pool["Database pool<br/>[db.py]"]
end

subgraph group_ai["AI and calculations"]
  node_ai_tools["AI analysis API<br/>[router.py]"]
  node_chat["Legal RAG chat"]
  node_calculators["Legal calculators<br/>[router.py]"]
end

subgraph group_worker["Background processing"]
  node_worker["Job worker<br/>[main.py]"]
  node_analysis["Document analysis<br/>[ai_service.py]"]
  node_pipeline["Gemini pipeline<br/>[pipeline.py]"]
  node_rag_ingest["RAG ingestion<br/>[rag_ingest.py]"]
  node_pension["Pension engine<br/>[engine.py]"]
end

subgraph group_infra["Data and integrations"]
  node_supabase[("Supabase services<br/>[supabase.py]")]
  node_storage["Document storage<br/>[storage.py]"]
  node_stripe["Stripe"]
  node_gemini["Google Gemini"]
end

node_user(("Office user"))
node_client(("Portal client"))

node_user -->|"uses"| node_frontend
node_client -->|"uses portal"| node_frontend
node_frontend -->|"calls API"| node_backend_api
node_frontend -->|"authenticates"| node_auth
node_backend_api -->|"serves features"| node_office
node_backend_api -->|"serves portal"| node_portal
node_backend_api -->|"serves features"| node_blog
node_backend_api -->|"serves features"| node_profiles
node_backend_api -->|"serves billing"| node_billing
node_backend_api -->|"routes requests"| node_ai_tools
node_backend_api -->|"routes requests"| node_chat
node_backend_api -->|"routes requests"| node_calculators
node_ai_tools -->|"queues jobs"| node_job_store
node_calculators -->|"queues jobs"| node_job_store
node_job_store -->|"reads and writes"| node_db_pool
node_worker -->|"claims jobs"| node_job_store
node_worker -->|"dispatches analysis"| node_analysis
node_analysis -->|"runs analysis"| node_pipeline
node_pipeline -->|"sends documents"| node_gemini
node_worker -->|"dispatches ingestion"| node_rag_ingest
node_worker -->|"calculates scenarios"| node_pension
node_rag_ingest -->|"stores chunks"| node_supabase
node_backend_api -->|"uses services"| node_supabase
node_worker -->|"prepares documents"| node_storage
node_billing -->|"processes payments"| node_stripe
node_frontend -->|"offers tools"| node_calculators

click node_frontend "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/frontend/src/App.tsx"
click node_auth "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/frontend/src/features/auth/services/auth-service.ts"
click node_office "https://github.com/marcelogcardozo/processa-ai/tree/main/apps/backend/src/features/office"
click node_portal "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/portal/service.py"
click node_blog "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/core/blog/service.py"
click node_backend_api "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/main.py"
click node_profiles "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/core/profiles/service.py"
click node_billing "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/billing/subscriptions/service.py"
click node_job_store "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/core/job_store.py"
click node_db_pool "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/core/db.py"
click node_ai_tools "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/ai/router.py"
click node_chat "https://github.com/marcelogcardozo/processa-ai/tree/main/apps/backend/src/features/ai/chat"
click node_calculators "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/calculators/router.py"
click node_worker "https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/main.py"
click node_analysis "https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/handlers/ai_service.py"
click node_pipeline "https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/handlers/pipeline.py"
click node_rag_ingest "https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/handlers/rag_ingest.py"
click node_pension "https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/handlers/previdencia/engine.py"
click node_supabase "https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/core/supabase.py"
click node_storage "https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/core/storage.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_auth,node_office,node_portal,node_blog,node_user,node_client toneBlue
class node_backend_api,node_profiles,node_billing,node_job_store,node_db_pool toneAmber
class node_ai_tools,node_chat,node_calculators toneMint
class node_worker,node_analysis,node_pipeline,node_rag_ingest,node_pension toneRose
class node_supabase,node_storage,node_stripe,node_gemini toneIndigo
```

## Components

### User applications

- [React application](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/frontend/src/App.tsx): `apps/frontend/src/App.tsx`
- [Authentication](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/frontend/src/features/auth/services/auth-service.ts): `apps/frontend/src/features/auth/services/auth-service.ts`
- [Office management](https://github.com/marcelogcardozo/processa-ai/tree/main/apps/backend/src/features/office): `apps/backend/src/features/office`
- [Client portal](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/portal/service.py): `apps/backend/src/features/portal/service.py`
- [Blog and materials](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/core/blog/service.py): `apps/backend/src/features/core/blog/service.py`

### Backend services

- [FastAPI service](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/main.py): `apps/backend/src/main.py`
- [Profiles and dashboard](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/core/profiles/service.py): `apps/backend/src/features/core/profiles/service.py`
- [Billing and credits](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/billing/subscriptions/service.py): `apps/backend/src/features/billing/subscriptions/service.py`
- [Job store](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/core/job_store.py): `apps/backend/src/core/job_store.py`
- [Database pool](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/core/db.py): `apps/backend/src/core/db.py`

### AI and calculations

- [AI analysis API](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/ai/router.py): `apps/backend/src/features/ai/router.py`
- [Legal RAG chat](https://github.com/marcelogcardozo/processa-ai/tree/main/apps/backend/src/features/ai/chat): `apps/backend/src/features/ai/chat`
- [Legal calculators](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/features/calculators/router.py): `apps/backend/src/features/calculators/router.py`

### Background processing

- [Job worker](https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/main.py): `services/worker/src/main.py`
- [Document analysis](https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/handlers/ai_service.py): `services/worker/src/handlers/ai_service.py`
- [Gemini pipeline](https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/handlers/pipeline.py): `services/worker/src/handlers/pipeline.py`
- [RAG ingestion](https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/handlers/rag_ingest.py): `services/worker/src/handlers/rag_ingest.py`
- [Pension engine](https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/handlers/previdencia/engine.py): `services/worker/src/handlers/previdencia/engine.py`

### Data and integrations

- [Supabase services](https://github.com/marcelogcardozo/processa-ai/blob/main/apps/backend/src/core/supabase.py): `apps/backend/src/core/supabase.py`
- [Document storage](https://github.com/marcelogcardozo/processa-ai/blob/main/services/worker/src/core/storage.py): `services/worker/src/core/storage.py`
- **Stripe**
- **Google Gemini**

### Other components

- **Office user**
- **Portal client**

## Connections

- Office user → React application: uses (evidence: `README.md`)
- Portal client → React application: uses portal (evidence: `README.md`)
- React application → FastAPI service: calls API (evidence: `README.md`)
- React application → Authentication: authenticates (evidence: `README.md`)
- FastAPI service → Office management: serves features (evidence: `README.md`)
- FastAPI service → Client portal: serves portal (evidence: `apps/backend/src/main.py`)
- FastAPI service → Blog and materials: serves features (evidence: `apps/backend/src/main.py`)
- FastAPI service → Profiles and dashboard: serves features (evidence: `apps/backend/src/main.py`)
- FastAPI service → Billing and credits: serves billing (evidence: `README.md`)
- FastAPI service → AI analysis API: routes requests (evidence: `apps/backend/src/main.py`)
- FastAPI service → Legal RAG chat: routes requests
- FastAPI service → Legal calculators: routes requests (evidence: `apps/backend/src/main.py`)
- AI analysis API → Job store: queues jobs (evidence: `apps/backend/src/features/ai/router.py`)
- Legal calculators → Job store: queues jobs (evidence: `apps/backend/src/features/calculators/router.py`)
- Job store → Database pool: reads and writes (evidence: `apps/backend/src/core/job_store.py`)
- Job worker → Job store: claims jobs (evidence: `services/worker/src/main.py`)
- Job worker → Document analysis: dispatches analysis (evidence: `services/worker/src/main.py`)
- Document analysis → Gemini pipeline: runs analysis (evidence: `services/worker/src/handlers/ai_service.py`)
- Gemini pipeline → Google Gemini: sends documents (evidence: `services/worker/src/handlers/pipeline.py`)
- Job worker → RAG ingestion: dispatches ingestion (evidence: `services/worker/src/main.py`)
- Job worker → Pension engine: calculates scenarios (evidence: `services/worker/src/main.py`)
- RAG ingestion → Supabase services: stores chunks (evidence: `services/worker/src/handlers/rag_ingest.py`)
- FastAPI service → Supabase services: uses services
- Job worker → Document storage: prepares documents (evidence: `services/worker/src/main.py`)
- Billing and credits → Stripe: processes payments (evidence: `README.md`)
- React application → Legal calculators: offers tools (evidence: `README.md`)
