# dadosjusbr/api architecture

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

- Interactive diagram: https://gitdiagram.com/dadosjusbr/api
- Repository: https://github.com/dadosjusbr/api

## Overview

DadosJusBr is a Go API serving consolidated, open judicial remuneration data to the public and portal clients. Its workflow begins with HTTP requests for agency and remuneration information, filtered search/downloads, or transparency indexes; handlers retrieve stored collection results and return summaries or raw data, with search results optionally fetched from S3 and serialized as CSV. The README describes upstream collectors and storage, but this repository exposes the API rather than implementing collection or normalization. Handler internals are only partially sampled, so uncertain route-to-storage details are not expanded.

Main entry points: [`uiapi/handlers.go`](https://github.com/dadosjusbr/api/blob/main/uiapi/handlers.go) (Portal handlers), [`main.go`](https://github.com/dadosjusbr/api/blob/main/main.go) (Server and routes), [`papi/handlers.go`](https://github.com/dadosjusbr/api/blob/main/papi/handlers.go) (Public handlers), [`uiapi/postgres.go`](https://github.com/dadosjusbr/api/blob/main/uiapi/postgres.go) (Search database adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP entrypoints"]
  node_server["Server and routes<br/>[main.go]"]
end

subgraph group_portal["Portal API"]
  node_portal_handlers["Portal handlers<br/>[handlers.go]"]
  node_search_params["Search filters<br/>[search_params.go]"]
  node_search_db["Search database adapter<br/>[postgres.go]"]
  node_s3_search["Archive search<br/>[aws.go]"]
  node_portal_models["Portal response models<br/>[models.go]"]
end

subgraph group_public["Public data API"]
  node_public_handlers["Public handlers<br/>[handlers.go]"]
  node_public_models["Public response models<br/>[models.go]"]
end

subgraph group_data["Data access"]
  node_storage_client["Storage client"]
  node_postgres[("PostgreSQL")]
  node_s3[("AWS S3")]
end

node_consumer(("API consumer"))
node_collectors["Upstream collectors"]

node_consumer -->|"sends HTTP requests"| node_server
node_server -->|"dispatches portal routes"| node_portal_handlers
node_server -->|"dispatches public routes"| node_public_handlers
node_server -->|"constructs client"| node_storage_client
node_portal_handlers -->|"reads agency data"| node_storage_client
node_public_handlers -->|"reads stored data"| node_storage_client
node_portal_handlers -->|"parses search filters"| node_search_params
node_portal_handlers -->|"queries filtered records"| node_search_db
node_search_db -->|"runs SQL queries"| node_postgres
node_portal_handlers -->|"requests archive rows"| node_s3_search
node_s3_search -->|"downloads ZIP objects"| node_s3
node_portal_handlers -->|"builds API responses"| node_portal_models
node_public_handlers -->|"builds API responses"| node_public_models
node_storage_client -->|"reads stored records"| node_postgres
node_storage_client -->|"reads stored files"| node_s3

click node_server "https://github.com/dadosjusbr/api/blob/main/main.go"
click node_portal_handlers "https://github.com/dadosjusbr/api/blob/main/uiapi/handlers.go"
click node_search_params "https://github.com/dadosjusbr/api/blob/main/uiapi/search_params.go"
click node_search_db "https://github.com/dadosjusbr/api/blob/main/uiapi/postgres.go"
click node_s3_search "https://github.com/dadosjusbr/api/blob/main/uiapi/aws.go"
click node_portal_models "https://github.com/dadosjusbr/api/blob/main/uiapi/models.go"
click node_public_handlers "https://github.com/dadosjusbr/api/blob/main/papi/handlers.go"
click node_public_models "https://github.com/dadosjusbr/api/blob/main/papi/models.go"

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_server toneBlue
class node_portal_handlers,node_search_params,node_search_db,node_s3_search,node_portal_models toneAmber
class node_public_handlers,node_public_models,node_consumer toneMint
class node_storage_client,node_postgres,node_s3 toneRose
class node_collectors toneIndigo
```

## Components

### HTTP entrypoints

- [Server and routes](https://github.com/dadosjusbr/api/blob/main/main.go): `main.go`

### Portal API

- [Portal handlers](https://github.com/dadosjusbr/api/blob/main/uiapi/handlers.go): `uiapi/handlers.go`
- [Search filters](https://github.com/dadosjusbr/api/blob/main/uiapi/search_params.go): `uiapi/search_params.go`
- [Search database adapter](https://github.com/dadosjusbr/api/blob/main/uiapi/postgres.go): `uiapi/postgres.go`
- [Archive search](https://github.com/dadosjusbr/api/blob/main/uiapi/aws.go): `uiapi/aws.go`
- [Portal response models](https://github.com/dadosjusbr/api/blob/main/uiapi/models.go): `uiapi/models.go`

### Public data API

- [Public handlers](https://github.com/dadosjusbr/api/blob/main/papi/handlers.go): `papi/handlers.go`
- [Public response models](https://github.com/dadosjusbr/api/blob/main/papi/models.go): `papi/models.go`

### Data access

- **Storage client**
- **PostgreSQL**
- **AWS S3**

### Other components

- **API consumer**
- **Upstream collectors**

## Connections

- API consumer → Server and routes: sends HTTP requests
- Server and routes → Portal handlers: dispatches portal routes
- Server and routes → Public handlers: dispatches public routes
- Server and routes → Storage client: constructs client
- Portal handlers → Storage client: reads agency data
- Public handlers → Storage client: reads stored data
- Portal handlers → Search filters: parses search filters
- Portal handlers → Search database adapter: queries filtered records
- Search database adapter → PostgreSQL: runs SQL queries
- Portal handlers → Archive search: requests archive rows
- Archive search → AWS S3: downloads ZIP objects
- Portal handlers → Portal response models: builds API responses
- Public handlers → Public response models: builds API responses
- Storage client → PostgreSQL: reads stored records
- Storage client → AWS S3: reads stored files