# femathrl0/lexai architecture

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

- Interactive diagram: https://gitdiagram.com/femathrl0/lexai
- Repository: https://github.com/femathrl0/lexai

## Overview

Lexai is a worker-facing application for helping people understand labor-case documents: it promises plain-language explanations with cited evidence, not legal advice. The documented user workflow is document upload, reading and classification, legal-evidence retrieval, explanation, quality verification, and streamed results; the sampled worker pipeline is explicitly still a skeleton that publishes statuses rather than performing those analysis stages. A separate major branch prepares and validates jurisprudence for indexing. Several analysis and integration links below rely on README descriptions because their implementation was not sampled.

Main entry points: [`worker/pipelines.py`](https://github.com/femathrl0/lexai/blob/main/worker/pipelines.py) (Task pipelines), [`backend/main.py`](https://github.com/femathrl0/lexai/blob/main/backend/main.py) (FastAPI endpoints), [`worker/main.py`](https://github.com/femathrl0/lexai/blob/main/worker/main.py) (Worker queue entry), [`worker/ingestao/jurisprudencia/automatic_review.py`](https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/automatic_review.py) (Automated review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_frontend["Upload and results UI<br/>[App.tsx]"]
end

subgraph group_orchestration["API and worker"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_redis["Redis task queues"]
  node_worker["Worker queue entry<br/>[main.py]"]
  node_pipelines["Task pipelines<br/>[pipelines.py]"]
end

subgraph group_analysis["Document analysis"]
  node_reader["Document reading"]
  node_classification["Classification and models"]
  node_retrieval["Evidence retrieval<br/>[recuperador.py]"]
  node_explanation["Explanation and checks<br/>[explicador.py]"]
  node_legal_index[("Legal vector index<br/>[pgvector_store.py]")]
end

subgraph group_corpus["Jurisprudence ingestion"]
  node_ingest_flow["Jurisprudence preparation"]
  node_audit["Corpus audit and review<br/>[audit.py]"]
  node_automatic_review["Automated review"]
  node_chunking["Definitive chunking"]
  node_embeddings["Corpus embeddings"]
  node_backbone["Embedding backbone"]
end

subgraph group_contracts["Contracts and persistence"]
  node_contracts["Typed event contracts<br/>[base.py]"]
end

node_person(("Document user"))

node_person -->|"uploads document"| node_frontend
node_frontend -->|"submits upload"| node_api
node_api -->|"enqueues task"| node_redis
node_api -->|"subscribes to task channel"| node_worker
node_worker -.->|"reads task queues"| node_redis
node_worker -.->|"dispatches tasks"| node_pipelines
node_pipelines -->|"publishes task events"| node_redis
node_pipelines -->|"publishes typed events"| node_contracts
node_pipelines -.->|"announces reading stage"| node_reader
node_pipelines -.->|"announces classification stage"| node_classification
node_pipelines -.->|"announces retrieval stage"| node_retrieval
node_pipelines -.->|"announces writing stage"| node_explanation
node_retrieval -.->|"retrieves evidence"| node_legal_index
node_ingest_flow -.->|"runs audit stage"| node_audit
node_ingest_flow -->|"runs review stage"| node_automatic_review
node_automatic_review -->|"uses audit utilities"| node_audit
node_automatic_review -.->|"passes reviewed corpus"| node_chunking
node_chunking -->|"provides chunks"| node_embeddings
node_embeddings -->|"generates vectors"| node_backbone
node_backbone -->|"checks index compatibility"| node_legal_index

click node_frontend "https://github.com/femathrl0/lexai/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/femathrl0/lexai/blob/main/backend/main.py"
click node_worker "https://github.com/femathrl0/lexai/blob/main/worker/main.py"
click node_pipelines "https://github.com/femathrl0/lexai/blob/main/worker/pipelines.py"
click node_contracts "https://github.com/femathrl0/lexai/blob/main/contratos/base.py"
click node_reader "https://github.com/femathrl0/lexai/tree/main/worker/leitura"
click node_classification "https://github.com/femathrl0/lexai/tree/main/worker/modelos"
click node_retrieval "https://github.com/femathrl0/lexai/blob/main/worker/evidencia/recuperador.py"
click node_explanation "https://github.com/femathrl0/lexai/blob/main/worker/evidencia/explicador.py"
click node_legal_index "https://github.com/femathrl0/lexai/blob/main/worker/evidencia/indices/pgvector_store.py"
click node_ingest_flow "https://github.com/femathrl0/lexai/tree/main/worker/ingestao/jurisprudencia"
click node_audit "https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/audit.py"
click node_automatic_review "https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/automatic_review.py"
click node_chunking "https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/chunking_definitivo.py"
click node_embeddings "https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/embeddings_definitivos.py"
click node_backbone "https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/embeddings_backbone.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_person toneBlue
class node_api,node_redis,node_worker,node_pipelines toneAmber
class node_reader,node_classification,node_retrieval,node_explanation,node_legal_index toneMint
class node_ingest_flow,node_audit,node_automatic_review,node_chunking,node_embeddings,node_backbone toneRose
class node_contracts toneIndigo
```

## Components

### User experience

- [Upload and results UI](https://github.com/femathrl0/lexai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### API and worker

- [FastAPI endpoints](https://github.com/femathrl0/lexai/blob/main/backend/main.py): `backend/main.py`
- **Redis task queues**
- [Worker queue entry](https://github.com/femathrl0/lexai/blob/main/worker/main.py): `worker/main.py`
- [Task pipelines](https://github.com/femathrl0/lexai/blob/main/worker/pipelines.py): `worker/pipelines.py`

### Document analysis

- [Document reading](https://github.com/femathrl0/lexai/tree/main/worker/leitura): `worker/leitura`
- [Classification and models](https://github.com/femathrl0/lexai/tree/main/worker/modelos): `worker/modelos`
- [Evidence retrieval](https://github.com/femathrl0/lexai/blob/main/worker/evidencia/recuperador.py): `worker/evidencia/recuperador.py`
- [Explanation and checks](https://github.com/femathrl0/lexai/blob/main/worker/evidencia/explicador.py): `worker/evidencia/explicador.py`
- [Legal vector index](https://github.com/femathrl0/lexai/blob/main/worker/evidencia/indices/pgvector_store.py): `worker/evidencia/indices/pgvector_store.py`

### Jurisprudence ingestion

- [Jurisprudence preparation](https://github.com/femathrl0/lexai/tree/main/worker/ingestao/jurisprudencia): `worker/ingestao/jurisprudencia`
- [Corpus audit and review](https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/audit.py): `worker/ingestao/jurisprudencia/audit.py`
- [Automated review](https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/automatic_review.py): `worker/ingestao/jurisprudencia/automatic_review.py`
- [Definitive chunking](https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/chunking_definitivo.py): `worker/ingestao/jurisprudencia/chunking_definitivo.py`
- [Corpus embeddings](https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/embeddings_definitivos.py): `worker/ingestao/jurisprudencia/embeddings_definitivos.py`
- [Embedding backbone](https://github.com/femathrl0/lexai/blob/main/worker/ingestao/jurisprudencia/embeddings_backbone.py): `worker/ingestao/jurisprudencia/embeddings_backbone.py`

### Contracts and persistence

- [Typed event contracts](https://github.com/femathrl0/lexai/blob/main/contratos/base.py): `contratos/base.py`

### Other components

- **Document user**

## Connections

- Document user → Upload and results UI: uploads document (evidence: `frontend/src/App.tsx`)
- Upload and results UI → FastAPI endpoints: submits upload (evidence: `frontend/src/App.tsx`)
- FastAPI endpoints → Redis task queues: enqueues task (evidence: `backend/main.py`)
- FastAPI endpoints → Worker queue entry: subscribes to task channel (evidence: `backend/main.py`)
- Worker queue entry → Redis task queues: reads task queues
- Worker queue entry → Task pipelines: dispatches tasks
- Task pipelines → Redis task queues: publishes task events (evidence: `worker/pipelines.py`)
- Task pipelines → Typed event contracts: publishes typed events (evidence: `worker/pipelines.py`)
- Task pipelines → Document reading: announces reading stage
- Task pipelines → Classification and models: announces classification stage
- Task pipelines → Evidence retrieval: announces retrieval stage
- Task pipelines → Explanation and checks: announces writing stage
- Evidence retrieval → Legal vector index: retrieves evidence
- Jurisprudence preparation → Corpus audit and review: runs audit stage (evidence: `worker/ingestao/jurisprudencia/automatic_review.py`)
- Jurisprudence preparation → Automated review: runs review stage (evidence: `worker/ingestao/scripts/rodar_pipeline_base_reduzida.py`)
- Automated review → Corpus audit and review: uses audit utilities (evidence: `worker/ingestao/jurisprudencia/automatic_review.py`)
- Automated review → Definitive chunking: passes reviewed corpus (evidence: `worker/ingestao/jurisprudencia/chunking_definitivo.py`)
- Definitive chunking → Corpus embeddings: provides chunks (evidence: `worker/ingestao/jurisprudencia/embeddings_definitivos.py`)
- Corpus embeddings → Embedding backbone: generates vectors (evidence: `worker/ingestao/jurisprudencia/embeddings_definitivos.py`)
- Embedding backbone → Legal vector index: checks index compatibility (evidence: `worker/ingestao/jurisprudencia/embeddings_backbone.py`)
