# dev-macb/breve-link architecture

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

- Interactive diagram: https://gitdiagram.com/dev-macb/breve-link
- Repository: https://github.com/dev-macb/breve-link

## Overview

Breve Link is a URL shortener with an administrative React panel, API, and local SQLite-backed access analytics. The main workflow is an administrator creating or managing a short link, a visitor requesting its slug, and the API redirecting to the destination while recording a GET access; administrators can then inspect link statistics and QR codes. The graph also covers authentication, user administration, and legacy collection. Relationships are grounded in the README and shown excerpts; unsampled route-to-controller wiring is left out where it cannot be verified.

Main entry points: [`api/src/app.ts`](https://github.com/dev-macb/breve-link/blob/main/api/src/app.ts) (Express server), [`api/src/controllers/LinkController.ts`](https://github.com/dev-macb/breve-link/blob/main/api/src/controllers/LinkController.ts) (Link HTTP actions), [`app/src/app/App.tsx`](https://github.com/dev-macb/breve-link/blob/main/app/src/app/App.tsx) (App routes), [`app/src/services/http.ts`](https://github.com/dev-macb/breve-link/blob/main/app/src/services/http.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Admin panel"]
  node_app["App routes<br/>[App.tsx]"]
  node_session["Web session<br/>[Sessao.tsx]"]
  node_http["HTTP client<br/>[http.ts]"]
  node_links_ui["Link dashboard<br/>[Dashboard.tsx]"]
  node_stats_ui["Statistics view<br/>[Estatisticas.tsx]"]
  node_stats_hook["Statistics data<br/>[useEstatisticas.ts]"]
  node_users_ui["User administration<br/>[Usuarios.tsx]"]
  node_web_support["Session and notices UI"]
end

subgraph group_api["HTTP API"]
  node_server["Express server<br/>[app.ts]"]
  node_auth_routes["Authentication routes"]
  node_auth_guard["Session authentication"]
  node_link_controller["Link HTTP actions<br/>[LinkController.ts]"]
  node_user_controller["User HTTP actions"]
end

subgraph group_domain["Link and account domain"]
  node_link_service["Link rules<br/>[LinkService.ts]"]
  node_user_service["User and login rules<br/>[UsuarioService.ts]"]
  node_qr["QR generation<br/>[QrCodeUtil.ts]"]
  node_access_collect["Access collection"]
end

subgraph group_data["Persistence and analytics"]
  node_link_repo["Link records<br/>[LinkRepository.ts]"]
  node_user_repo["User records"]
  node_access_repo["Access analytics"]
  node_geo["Legacy geo collection"]
  node_sqlite[("SQLite database<br/>[Ambiente.ts]")]
end

subgraph group_runtime["Runtime configuration"]
  node_container["Dependency wiring<br/>[Conteiner.ts]"]
  node_web_config["Web and session config"]
  node_api_config["API configuration<br/>[Ambiente.ts]"]
end

node_admin(("Administrator"))
node_visitor(("Link visitor"))

node_admin -->|"uses panel"| node_app
node_app -->|"provides session"| node_session
node_app -->|"routes to"| node_links_ui
node_app -->|"routes to"| node_stats_ui
node_app -->|"routes to"| node_users_ui
node_links_ui -.->|"requests API"| node_http
node_stats_ui -.->|"renders data"| node_stats_hook
node_stats_hook -->|"fetches stats"| node_http
node_users_ui -->|"requests API"| node_http
node_session -->|"checks session"| node_http
node_http -.->|"sends requests"| node_server
node_visitor -->|"requests slug"| node_server
node_server -->|"dispatches redirect"| node_link_controller
node_server -->|"mounts auth"| node_auth_routes
node_auth_routes -->|"dispatches login"| node_user_controller
node_auth_routes -->|"guards session routes"| node_auth_guard
node_auth_guard -->|"revalidates session"| node_sqlite
node_link_controller -->|"runs link actions"| node_link_service
node_user_controller -->|"runs user actions"| node_user_service
node_link_controller -->|"generates QR"| node_qr
node_link_controller -->|"collects request data"| node_access_collect
node_link_controller -->|"redirects to destination"| node_visitor
node_link_service -->|"uses link records"| node_link_repo
node_user_service -->|"uses user records"| node_user_repo
node_link_service -.->|"records access"| node_access_repo
node_access_repo -->|"reads and writes"| node_sqlite
node_link_repo -->|"reads and writes"| node_sqlite
node_user_repo -.->|"persists accounts"| node_sqlite
node_server -->|"accepts legacy collection"| node_geo
node_geo -.->|"stores legacy geo data"| node_sqlite
node_container -->|"registers controller"| node_link_controller
node_api_config -->|"configures runtime"| node_server
node_web_config -->|"sets web behavior"| node_server

click node_app "https://github.com/dev-macb/breve-link/blob/main/app/src/app/App.tsx"
click node_session "https://github.com/dev-macb/breve-link/blob/main/app/src/app/Sessao.tsx"
click node_http "https://github.com/dev-macb/breve-link/blob/main/app/src/services/http.ts"
click node_links_ui "https://github.com/dev-macb/breve-link/blob/main/app/src/paginas/Dashboard.tsx"
click node_stats_ui "https://github.com/dev-macb/breve-link/blob/main/app/src/paginas/Estatisticas.tsx"
click node_stats_hook "https://github.com/dev-macb/breve-link/blob/main/app/src/funcionalidades/estatisticas/useEstatisticas.ts"
click node_users_ui "https://github.com/dev-macb/breve-link/blob/main/app/src/paginas/Usuarios.tsx"
click node_web_support "https://github.com/dev-macb/breve-link/tree/main/app/src/app"
click node_server "https://github.com/dev-macb/breve-link/blob/main/api/src/app.ts"
click node_auth_routes "https://github.com/dev-macb/breve-link/blob/main/api/src/routes/AutenticacaoRouter.ts"
click node_auth_guard "https://github.com/dev-macb/breve-link/blob/main/api/src/middlewares/AutenticacaoMiddleware.ts"
click node_link_controller "https://github.com/dev-macb/breve-link/blob/main/api/src/controllers/LinkController.ts"
click node_user_controller "https://github.com/dev-macb/breve-link/blob/main/api/src/controllers/UsuarioController.ts"
click node_link_service "https://github.com/dev-macb/breve-link/blob/main/api/src/services/LinkService.ts"
click node_user_service "https://github.com/dev-macb/breve-link/blob/main/api/src/services/UsuarioService.ts"
click node_qr "https://github.com/dev-macb/breve-link/blob/main/api/src/utils/QrCodeUtil.ts"
click node_access_collect "https://github.com/dev-macb/breve-link/blob/main/api/src/utils/ColetaAcessoUtil.ts"
click node_link_repo "https://github.com/dev-macb/breve-link/blob/main/api/src/repositories/LinkRepository.ts"
click node_user_repo "https://github.com/dev-macb/breve-link/blob/main/api/src/repositories/UsuarioRepository.ts"
click node_access_repo "https://github.com/dev-macb/breve-link/blob/main/api/src/repositories/AcessoRepository.ts"
click node_geo "https://github.com/dev-macb/breve-link/blob/main/api/src/services/GeolocalizacaoService.ts"
click node_sqlite "https://github.com/dev-macb/breve-link/blob/main/api/src/config/knex/Ambiente.ts"
click node_container "https://github.com/dev-macb/breve-link/blob/main/api/src/config/Conteiner.ts"
click node_web_config "https://github.com/dev-macb/breve-link/tree/main/api/src/config"
click node_api_config "https://github.com/dev-macb/breve-link/blob/main/api/src/config/Ambiente.ts"

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_app,node_session,node_http,node_links_ui,node_stats_ui,node_stats_hook,node_users_ui,node_web_support toneBlue
class node_server,node_auth_routes,node_auth_guard,node_link_controller,node_user_controller toneAmber
class node_link_service,node_user_service,node_qr,node_access_collect toneMint
class node_link_repo,node_user_repo,node_access_repo,node_geo,node_sqlite toneRose
class node_container,node_web_config,node_api_config,node_admin,node_visitor toneIndigo
```

## Components

### Admin panel

- [App routes](https://github.com/dev-macb/breve-link/blob/main/app/src/app/App.tsx): `app/src/app/App.tsx`
- [Web session](https://github.com/dev-macb/breve-link/blob/main/app/src/app/Sessao.tsx): `app/src/app/Sessao.tsx`
- [HTTP client](https://github.com/dev-macb/breve-link/blob/main/app/src/services/http.ts): `app/src/services/http.ts`
- [Link dashboard](https://github.com/dev-macb/breve-link/blob/main/app/src/paginas/Dashboard.tsx): `app/src/paginas/Dashboard.tsx`
- [Statistics view](https://github.com/dev-macb/breve-link/blob/main/app/src/paginas/Estatisticas.tsx): `app/src/paginas/Estatisticas.tsx`
- [Statistics data](https://github.com/dev-macb/breve-link/blob/main/app/src/funcionalidades/estatisticas/useEstatisticas.ts): `app/src/funcionalidades/estatisticas/useEstatisticas.ts`
- [User administration](https://github.com/dev-macb/breve-link/blob/main/app/src/paginas/Usuarios.tsx): `app/src/paginas/Usuarios.tsx`
- [Session and notices UI](https://github.com/dev-macb/breve-link/tree/main/app/src/app): `app/src/app`

### HTTP API

- [Express server](https://github.com/dev-macb/breve-link/blob/main/api/src/app.ts): `api/src/app.ts`
- [Authentication routes](https://github.com/dev-macb/breve-link/blob/main/api/src/routes/AutenticacaoRouter.ts): `api/src/routes/AutenticacaoRouter.ts`
- [Session authentication](https://github.com/dev-macb/breve-link/blob/main/api/src/middlewares/AutenticacaoMiddleware.ts): `api/src/middlewares/AutenticacaoMiddleware.ts`
- [Link HTTP actions](https://github.com/dev-macb/breve-link/blob/main/api/src/controllers/LinkController.ts): `api/src/controllers/LinkController.ts`
- [User HTTP actions](https://github.com/dev-macb/breve-link/blob/main/api/src/controllers/UsuarioController.ts): `api/src/controllers/UsuarioController.ts`

### Link and account domain

- [Link rules](https://github.com/dev-macb/breve-link/blob/main/api/src/services/LinkService.ts): `api/src/services/LinkService.ts`
- [User and login rules](https://github.com/dev-macb/breve-link/blob/main/api/src/services/UsuarioService.ts): `api/src/services/UsuarioService.ts`
- [QR generation](https://github.com/dev-macb/breve-link/blob/main/api/src/utils/QrCodeUtil.ts): `api/src/utils/QrCodeUtil.ts`
- [Access collection](https://github.com/dev-macb/breve-link/blob/main/api/src/utils/ColetaAcessoUtil.ts): `api/src/utils/ColetaAcessoUtil.ts`

### Persistence and analytics

- [Link records](https://github.com/dev-macb/breve-link/blob/main/api/src/repositories/LinkRepository.ts): `api/src/repositories/LinkRepository.ts`
- [User records](https://github.com/dev-macb/breve-link/blob/main/api/src/repositories/UsuarioRepository.ts): `api/src/repositories/UsuarioRepository.ts`
- [Access analytics](https://github.com/dev-macb/breve-link/blob/main/api/src/repositories/AcessoRepository.ts): `api/src/repositories/AcessoRepository.ts`
- [Legacy geo collection](https://github.com/dev-macb/breve-link/blob/main/api/src/services/GeolocalizacaoService.ts): `api/src/services/GeolocalizacaoService.ts`
- [SQLite database](https://github.com/dev-macb/breve-link/blob/main/api/src/config/knex/Ambiente.ts): `api/src/config/knex/Ambiente.ts`

### Runtime configuration

- [Dependency wiring](https://github.com/dev-macb/breve-link/blob/main/api/src/config/Conteiner.ts): `api/src/config/Conteiner.ts`
- [Web and session config](https://github.com/dev-macb/breve-link/tree/main/api/src/config): `api/src/config`
- [API configuration](https://github.com/dev-macb/breve-link/blob/main/api/src/config/Ambiente.ts): `api/src/config/Ambiente.ts`

### Other components

- **Administrator**
- **Link visitor**

## Connections

- Administrator → App routes: uses panel
- App routes → Web session: provides session (evidence: `app/src/app/App.tsx`)
- App routes → Link dashboard: routes to (evidence: `app/src/app/App.tsx`)
- App routes → Statistics view: routes to (evidence: `app/src/app/App.tsx`)
- App routes → User administration: routes to (evidence: `app/src/app/App.tsx`)
- Link dashboard → HTTP client: requests API
- Statistics view → Statistics data: renders data
- Statistics data → HTTP client: fetches stats (evidence: `app/src/funcionalidades/estatisticas/useEstatisticas.ts`)
- User administration → HTTP client: requests API (evidence: `app/src/paginas/Usuarios.tsx`)
- Web session → HTTP client: checks session (evidence: `app/src/app/Sessao.tsx`)
- HTTP client → Express server: sends requests
- Link visitor → Express server: requests slug
- Express server → Link HTTP actions: dispatches redirect (evidence: `api/src/app.ts`)
- Express server → Authentication routes: mounts auth (evidence: `api/src/app.ts`)
- Authentication routes → User HTTP actions: dispatches login (evidence: `api/src/routes/AutenticacaoRouter.ts`)
- Authentication routes → Session authentication: guards session routes (evidence: `api/src/routes/AutenticacaoRouter.ts`)
- Session authentication → SQLite database: revalidates session (evidence: `api/src/middlewares/AutenticacaoMiddleware.ts`)
- Link HTTP actions → Link rules: runs link actions
- User HTTP actions → User and login rules: runs user actions (evidence: `api/src/controllers/UsuarioController.ts`)
- Link HTTP actions → QR generation: generates QR (evidence: `api/src/controllers/LinkController.ts`)
- Link HTTP actions → Access collection: collects request data (evidence: `api/src/controllers/LinkController.ts`)
- Link HTTP actions → Link visitor: redirects to destination (evidence: `api/src/controllers/LinkController.ts`)
- Link rules → Link records: uses link records
- User and login rules → User records: uses user records
- Link rules → Access analytics: records access
- Access analytics → SQLite database: reads and writes (evidence: `api/src/repositories/AcessoRepository.ts`)
- Link records → SQLite database: reads and writes (evidence: `api/src/repositories/LinkRepository.ts`)
- User records → SQLite database: persists accounts
- Express server → Legacy geo collection: accepts legacy collection (evidence: `api/src/app.ts`)
- Legacy geo collection → SQLite database: stores legacy geo data
- Dependency wiring → Link HTTP actions: registers controller (evidence: `api/src/config/Conteiner.ts`)
- API configuration → Express server: configures runtime (evidence: `api/src/app.ts`)
- Web and session config → Express server: sets web behavior (evidence: `api/src/app.ts`)