# wesleysemende133/buscador_juridico architecture

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

- Interactive diagram: https://gitdiagram.com/wesleysemende133/buscador_juridico
- Repository: https://github.com/wesleysemende133/buscador_juridico

## Overview

Buscador Jurídico is a public legal-search API for Mozambican and PALOP legislation, with article administration and automated law collection. The main workflow is a request reaching an HTTP handler, passing through a search or administration service, and reading or changing articles in the configured repository. Separate capabilities include the AI legal assistant, user authentication and plans, categorization, duplicate cleanup, and crawling. The repository supports JSON and PostgreSQL storage. Some subsystem links are documented or visible in entry-point wiring; unsampled implementation details are not inferred.

Main entry points: [`main.go`](https://github.com/wesleysemende133/buscador_juridico/blob/main/main.go) (API server), [`internal/crawler/crawler.go`](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/crawler.go) (Law crawler), [`internal/domain/artigo.go`](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/domain/artigo.go) (Legal articles), [`internal/service/agente_service.go`](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/agente_service.go) (AI legal assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_server["API server<br/>[main.go]"]
  node_legacyserver["API entrypoint<br/>[main.go]"]
  node_searchhttp["Search handlers<br/>[busca_handler.go]"]
  node_adminhttp["Admin handlers<br/>[admin_handler.go]"]
  node_crawlerhttp["Crawler handler<br/>[crawler_handler.go]"]
  node_assistanthttp["Assistant handler<br/>[agente_handler.go]"]
  node_authhttp["Auth handlers<br/>[auth_handler.go]"]
  node_oauthhttp["OAuth handler<br/>[oauth_handler.go]"]
  node_planshttp["Plans handler<br/>[planos_handler.go]"]
end

subgraph group_law["Legislation workflows"]
  node_searchsvc["Legal search<br/>[busca_service.go]"]
  node_adminsvc["Article management<br/>[admin_service.go]"]
  node_categorysvc["Categorization"]
  node_dedupsvc["Deduplication<br/>[dedup_service.go]"]
  node_cleanupsvc["Duplicate cleanup<br/>[limpeza_service.go]"]
  node_articles["Legal articles<br/>[artigo.go]"]
end

subgraph group_assist["Assistant and accounts"]
  node_assistant["AI legal assistant<br/>[agente_service.go]"]
  node_limits["Usage limits<br/>[limites_service.go]"]
  node_authsvc["Authentication<br/>[auth_service.go]"]
  node_jwt["JWT and passwords<br/>[jwt.go]"]
  node_authmw["Auth middleware<br/>[middleware.go]"]
end

subgraph group_crawl["Law collection"]
  node_crawler["Law crawler<br/>[crawler.go]"]
  node_gemini["Gemini extractor"]
  node_regex["Regex extractor<br/>[regex_extractor.go]"]
  node_sources["Crawler sources<br/>[fontes.go]"]
end

subgraph group_storage["Persistence"]
  node_repojson["JSON repository<br/>[json_repository.go]"]
  node_repopg["PostgreSQL repository"]
  node_repoiface["Repository contracts<br/>[interfaces.go]"]
  node_jsondata[("Article data file<br/>[leis.json]")]
end

node_citizen(("Public user"))
node_adminuser(("Administrator"))
node_postgres[("PostgreSQL")]
node_geminiservice{{"Gemini API"}}
node_google{{"Google identity"}}

node_citizen -->|"sends request"| node_server
node_adminuser -->|"sends request"| node_server
node_server -->|"routes search"| node_searchhttp
node_server -->|"routes admin"| node_adminhttp
node_server -->|"routes crawling"| node_crawlerhttp
node_server -->|"routes assistant"| node_assistanthttp
node_server -.->|"routes auth"| node_authhttp
node_server -.->|"routes OAuth"| node_oauthhttp
node_server -->|"routes plans"| node_planshttp
node_legacyserver -->|"routes search"| node_searchhttp
node_legacyserver -->|"routes admin"| node_adminhttp
node_legacyserver -->|"routes crawling"| node_crawlerhttp
node_searchhttp -->|"calls"| node_searchsvc
node_adminhttp -->|"calls"| node_adminsvc
node_crawlerhttp -->|"calls"| node_adminsvc
node_crawlerhttp -->|"invokes"| node_crawler
node_assistanthttp -->|"calls"| node_assistant
node_authhttp -->|"creates tokens"| node_jwt
node_oauthhttp -->|"creates tokens"| node_jwt
node_oauthhttp -->|"validates token"| node_google
node_planshttp -->|"checks usage"| node_limits
node_searchsvc -->|"uses contract"| node_repoiface
node_adminsvc -->|"uses contract"| node_repoiface
node_assistant -->|"searches articles"| node_repoiface
node_assistant -->|"checks quota"| node_limits
node_assistant -.->|"requests generation"| node_geminiservice
node_repojson -->|"reads and writes"| node_jsondata
node_repopg -->|"queries"| node_postgres
node_server -->|"configures fallback"| node_repojson
node_server -->|"configures storage"| node_repopg
node_repojson -->|"loads and saves"| node_articles
node_repopg -->|"stores records"| node_articles
node_crawler -->|"extracts"| node_articles
node_crawler -.->|"may use extractor"| node_gemini
node_crawler -.->|"may use extractor"| node_regex
node_crawler -.->|"uses source list"| node_sources
node_categorysvc -->|"categorizes"| node_articles
node_dedupsvc -.->|"checks duplicates"| node_articles
node_cleanupsvc -->|"uses repository"| node_repoiface
node_server -.->|"initializes service"| node_categorysvc
node_server -->|"initializes service"| node_cleanupsvc

click node_server "https://github.com/wesleysemende133/buscador_juridico/blob/main/main.go"
click node_legacyserver "https://github.com/wesleysemende133/buscador_juridico/blob/main/cmd/api/main.go"
click node_searchhttp "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/busca_handler.go"
click node_adminhttp "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/admin_handler.go"
click node_crawlerhttp "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/crawler_handler.go"
click node_assistanthttp "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/agente_handler.go"
click node_authhttp "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/auth_handler.go"
click node_oauthhttp "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/oauth_handler.go"
click node_planshttp "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/planos_handler.go"
click node_searchsvc "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/busca_service.go"
click node_adminsvc "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/admin_service.go"
click node_categorysvc "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/categorizacao_service.go"
click node_dedupsvc "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/dedup_service.go"
click node_cleanupsvc "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/limpeza_service.go"
click node_articles "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/domain/artigo.go"
click node_assistant "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/agente_service.go"
click node_limits "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/limites_service.go"
click node_authsvc "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/auth_service.go"
click node_jwt "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/auth/jwt.go"
click node_authmw "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/auth/middleware.go"
click node_crawler "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/crawler.go"
click node_gemini "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/gemini_extractor.go"
click node_regex "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/regex_extractor.go"
click node_sources "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/fontes.go"
click node_repojson "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/repository/json/json_repository.go"
click node_repopg "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/repository/postgres/postgres_repository.go"
click node_repoiface "https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/repository/interfaces.go"
click node_jsondata "https://github.com/wesleysemende133/buscador_juridico/blob/main/data/leis.json"

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,node_legacyserver,node_searchhttp,node_adminhttp,node_crawlerhttp,node_assistanthttp,node_authhttp,node_oauthhttp,node_planshttp,node_citizen toneBlue
class node_searchsvc,node_adminsvc,node_categorysvc,node_dedupsvc,node_cleanupsvc,node_articles,node_postgres toneAmber
class node_assistant,node_limits,node_authsvc,node_jwt,node_authmw,node_geminiservice toneMint
class node_crawler,node_gemini,node_regex,node_sources toneRose
class node_repojson,node_repopg,node_repoiface,node_jsondata,node_adminuser,node_google toneIndigo
```

## Components

### HTTP API

- [API server](https://github.com/wesleysemende133/buscador_juridico/blob/main/main.go): `main.go`
- [API entrypoint](https://github.com/wesleysemende133/buscador_juridico/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [Search handlers](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/busca_handler.go): `internal/handler/busca_handler.go`
- [Admin handlers](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/admin_handler.go): `internal/handler/admin_handler.go`
- [Crawler handler](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/crawler_handler.go): `internal/handler/crawler_handler.go`
- [Assistant handler](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/agente_handler.go): `internal/handler/agente_handler.go`
- [Auth handlers](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/auth_handler.go): `internal/handler/auth_handler.go`
- [OAuth handler](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/oauth_handler.go): `internal/handler/oauth_handler.go`
- [Plans handler](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/handler/planos_handler.go): `internal/handler/planos_handler.go`

### Legislation workflows

- [Legal search](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/busca_service.go): `internal/service/busca_service.go`
- [Article management](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/admin_service.go): `internal/service/admin_service.go`
- [Categorization](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/categorizacao_service.go): `internal/service/categorizacao_service.go`
- [Deduplication](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/dedup_service.go): `internal/service/dedup_service.go`
- [Duplicate cleanup](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/limpeza_service.go): `internal/service/limpeza_service.go`
- [Legal articles](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/domain/artigo.go): `internal/domain/artigo.go`

### Assistant and accounts

- [AI legal assistant](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/agente_service.go): `internal/service/agente_service.go`
- [Usage limits](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/limites_service.go): `internal/service/limites_service.go`
- [Authentication](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/service/auth_service.go): `internal/service/auth_service.go`
- [JWT and passwords](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/auth/jwt.go): `internal/auth/jwt.go`
- [Auth middleware](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/auth/middleware.go): `internal/auth/middleware.go`

### Law collection

- [Law crawler](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/crawler.go): `internal/crawler/crawler.go`
- [Gemini extractor](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/gemini_extractor.go): `internal/crawler/gemini_extractor.go`
- [Regex extractor](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/regex_extractor.go): `internal/crawler/regex_extractor.go`
- [Crawler sources](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/crawler/fontes.go): `internal/crawler/fontes.go`

### Persistence

- [JSON repository](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/repository/json/json_repository.go): `internal/repository/json/json_repository.go`
- [PostgreSQL repository](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/repository/postgres/postgres_repository.go): `internal/repository/postgres/postgres_repository.go`
- [Repository contracts](https://github.com/wesleysemende133/buscador_juridico/blob/main/internal/repository/interfaces.go): `internal/repository/interfaces.go`
- [Article data file](https://github.com/wesleysemende133/buscador_juridico/blob/main/data/leis.json): `data/leis.json`

### Other components

- **Public user**
- **Administrator**
- **PostgreSQL**
- **Gemini API**
- **Google identity**

## Connections

- Public user → API server: sends request (evidence: `README.md`)
- Administrator → API server: sends request (evidence: `README.md`)
- API server → Search handlers: routes search (evidence: `main.go`)
- API server → Admin handlers: routes admin (evidence: `main.go`)
- API server → Crawler handler: routes crawling (evidence: `main.go`)
- API server → Assistant handler: routes assistant (evidence: `main.go`)
- API server → Auth handlers: routes auth
- API server → OAuth handler: routes OAuth
- API server → Plans handler: routes plans (evidence: `main.go`)
- API entrypoint → Search handlers: routes search (evidence: `cmd/api/main.go`)
- API entrypoint → Admin handlers: routes admin (evidence: `cmd/api/main.go`)
- API entrypoint → Crawler handler: routes crawling (evidence: `cmd/api/main.go`)
- Search handlers → Legal search: calls (evidence: `internal/handler/busca_handler.go`)
- Admin handlers → Article management: calls (evidence: `internal/handler/admin_handler.go`)
- Crawler handler → Article management: calls (evidence: `internal/handler/crawler_handler.go`)
- Crawler handler → Law crawler: invokes (evidence: `internal/handler/crawler_handler.go`)
- Assistant handler → AI legal assistant: calls (evidence: `internal/handler/agente_handler.go`)
- Auth handlers → JWT and passwords: creates tokens (evidence: `internal/handler/auth_handler.go`)
- OAuth handler → JWT and passwords: creates tokens (evidence: `internal/handler/oauth_handler.go`)
- OAuth handler → Google identity: validates token (evidence: `internal/handler/oauth_handler.go`)
- Plans handler → Usage limits: checks usage (evidence: `internal/handler/planos_handler.go`)
- Legal search → Repository contracts: uses contract (evidence: `internal/service/busca_service.go`)
- Article management → Repository contracts: uses contract (evidence: `internal/service/admin_service.go`)
- AI legal assistant → Repository contracts: searches articles (evidence: `internal/service/agente_service.go`)
- AI legal assistant → Usage limits: checks quota (evidence: `internal/service/agente_service.go`)
- AI legal assistant → Gemini API: requests generation
- JSON repository → Article data file: reads and writes
- PostgreSQL repository → PostgreSQL: queries (evidence: `internal/repository/postgres/postgres_repository.go`)
- API server → JSON repository: configures fallback (evidence: `main.go`)
- API server → PostgreSQL repository: configures storage (evidence: `main.go`)
- JSON repository → Legal articles: loads and saves (evidence: `internal/repository/json/json_repository.go`)
- PostgreSQL repository → Legal articles: stores records (evidence: `internal/repository/postgres/postgres_repository.go`)
- Law crawler → Legal articles: extracts (evidence: `internal/crawler/crawler.go`)
- Law crawler → Gemini extractor: may use extractor
- Law crawler → Regex extractor: may use extractor
- Law crawler → Crawler sources: uses source list
- Categorization → Legal articles: categorizes
- Deduplication → Legal articles: checks duplicates
- Duplicate cleanup → Repository contracts: uses repository (evidence: `internal/service/limpeza_service.go`)
- API server → Categorization: initializes service
- API server → Duplicate cleanup: initializes service (evidence: `main.go`)
