# luc45-pereira/api-tcc architecture

> Architecture diagram of the GitHub repository luc45-pereira/api-tcc, 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/luc45-pereira/api-tcc
- Repository: https://github.com/luc45-pereira/api-tcc

## Overview

This is a FastAPI personal-finance API: clients authenticate with JWTs, then manage users, addresses, cards, income and expenses, or connect a bank through Pluggy and retrieve accounts and transactions. The main entry point mounts these route families; sampled CRUD routes validate tokens and use SQLAlchemy sessions to read or mutate MySQL-backed models. The README also describes balance and bill notifications, but no implementation appears in the supplied tree. User/address and some Pluggy route behavior is represented from documented scope and paths; their source was not sampled.

Main entry points: [`main.py`](https://github.com/luc45-pereira/api-tcc/blob/main/main.py) (FastAPI app), [`internal/routers/PluggyRouter/transactions.py`](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/PluggyRouter/transactions.py) (Bank accounts and transactions), [`internal/Connection/conn.py`](https://github.com/luc45-pereira/api-tcc/blob/main/internal/Connection/conn.py) (SQLAlchemy sessions), [`internal/routers/PluggyRouter/access_pluggy.py`](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/PluggyRouter/access_pluggy.py) (Pluggy access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API routes"]
  node_app["FastAPI app<br/>[main.py]"]
  node_user_routes["User routes<br/>[user.py]"]
  node_address_routes["Address routes<br/>[endereco.py]"]
end

subgraph group_finance["Finance records"]
  node_card_routes["Card routes<br/>[cartao.py]"]
  node_income_routes["Income routes<br/>[entrada.py]"]
  node_expense_routes["Expense routes<br/>[saida.py]"]
end

subgraph group_persistence["Auth and storage"]
  node_jwt["JWT library"]
  node_token_helper["Token helper<br/>[token.py]"]
  node_request_models["Request schemas<br/>[pydantic.py]"]
  node_session["SQLAlchemy sessions<br/>[conn.py]"]
  node_orm_models["ORM models<br/>[Database.py]"]
end

subgraph group_bank["Bank integration"]
  node_pluggy_access["Pluggy access<br/>[access_pluggy.py]"]
  node_pluggy_transactions["Bank accounts and transactions<br/>[transactions.py]"]
  node_pluggy_models["Pluggy schemas<br/>[models.py]"]
end

node_client(("API client"))
node_mysql[("MySQL database")]
node_pluggy_service["Pluggy API"]

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_user_routes
node_app -->|"mounts routes"| node_address_routes
node_app -->|"mounts routes"| node_card_routes
node_app -->|"mounts routes"| node_income_routes
node_app -->|"mounts routes"| node_expense_routes
node_app -->|"mounts routes"| node_pluggy_access
node_app -->|"mounts routes"| node_pluggy_transactions
node_user_routes -->|"validates tokens"| node_jwt
node_address_routes -->|"validates tokens"| node_jwt
node_card_routes -->|"validates tokens"| node_jwt
node_income_routes -->|"validates tokens"| node_jwt
node_expense_routes -->|"validates tokens"| node_jwt
node_pluggy_access -->|"validates tokens"| node_jwt
node_pluggy_transactions -->|"validates tokens"| node_jwt
node_token_helper -->|"encodes and decodes"| node_jwt
node_card_routes -->|"uses schemas"| node_request_models
node_income_routes -->|"uses schemas"| node_request_models
node_expense_routes -->|"uses schemas"| node_request_models
node_pluggy_access -->|"uses token schema"| node_request_models
node_pluggy_transactions -->|"gets API key"| node_pluggy_access
node_pluggy_transactions -->|"validates responses"| node_pluggy_models
node_pluggy_access -->|"requests access and connectors"| node_pluggy_service
node_pluggy_transactions -->|"fetches bank data"| node_pluggy_service
node_user_routes -->|"opens sessions"| node_session
node_address_routes -->|"opens sessions"| node_session
node_card_routes -->|"opens sessions"| node_session
node_income_routes -->|"opens sessions"| node_session
node_expense_routes -->|"opens sessions"| node_session
node_pluggy_access -->|"opens sessions"| node_session
node_pluggy_transactions -->|"opens sessions"| node_session
node_session -->|"connects to"| node_mysql
node_card_routes -->|"queries and updates"| node_orm_models
node_income_routes -->|"queries and updates"| node_orm_models
node_expense_routes -->|"queries and updates"| node_orm_models
node_pluggy_access -->|"saves account link"| node_orm_models
node_pluggy_transactions -->|"reads and updates link"| node_orm_models
node_orm_models -->|"maps stored records"| node_mysql

click node_app "https://github.com/luc45-pereira/api-tcc/blob/main/main.py"
click node_user_routes "https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/user.py"
click node_address_routes "https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/endereco.py"
click node_card_routes "https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/cartao.py"
click node_income_routes "https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/entrada.py"
click node_expense_routes "https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/saida.py"
click node_pluggy_access "https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/PluggyRouter/access_pluggy.py"
click node_pluggy_transactions "https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/PluggyRouter/transactions.py"
click node_token_helper "https://github.com/luc45-pereira/api-tcc/blob/main/internal/Auth/token.py"
click node_request_models "https://github.com/luc45-pereira/api-tcc/blob/main/internal/models/pydantic.py"
click node_pluggy_models "https://github.com/luc45-pereira/api-tcc/blob/main/internal/models/PluggyModels/models.py"
click node_session "https://github.com/luc45-pereira/api-tcc/blob/main/internal/Connection/conn.py"
click node_orm_models "https://github.com/luc45-pereira/api-tcc/blob/main/internal/Database/Database.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_app,node_user_routes,node_address_routes,node_client toneBlue
class node_card_routes,node_income_routes,node_expense_routes,node_mysql toneAmber
class node_jwt,node_token_helper,node_request_models,node_session,node_orm_models,node_pluggy_service toneMint
class node_pluggy_access,node_pluggy_transactions,node_pluggy_models toneRose
```

## Components

### API routes

- [FastAPI app](https://github.com/luc45-pereira/api-tcc/blob/main/main.py): `main.py`
- [User routes](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/user.py): `internal/routers/user.py`
- [Address routes](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/endereco.py): `internal/routers/endereco.py`

### Finance records

- [Card routes](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/cartao.py): `internal/routers/cartao.py`
- [Income routes](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/entrada.py): `internal/routers/entrada.py`
- [Expense routes](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/saida.py): `internal/routers/saida.py`

### Auth and storage

- **JWT library**
- [Token helper](https://github.com/luc45-pereira/api-tcc/blob/main/internal/Auth/token.py): `internal/Auth/token.py`
- [Request schemas](https://github.com/luc45-pereira/api-tcc/blob/main/internal/models/pydantic.py): `internal/models/pydantic.py`
- [SQLAlchemy sessions](https://github.com/luc45-pereira/api-tcc/blob/main/internal/Connection/conn.py): `internal/Connection/conn.py`
- [ORM models](https://github.com/luc45-pereira/api-tcc/blob/main/internal/Database/Database.py): `internal/Database/Database.py`

### Bank integration

- [Pluggy access](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/PluggyRouter/access_pluggy.py): `internal/routers/PluggyRouter/access_pluggy.py`
- [Bank accounts and transactions](https://github.com/luc45-pereira/api-tcc/blob/main/internal/routers/PluggyRouter/transactions.py): `internal/routers/PluggyRouter/transactions.py`
- [Pluggy schemas](https://github.com/luc45-pereira/api-tcc/blob/main/internal/models/PluggyModels/models.py): `internal/models/PluggyModels/models.py`

### Other components

- **API client**
- **MySQL database**
- **Pluggy API**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → User routes: mounts routes
- FastAPI app → Address routes: mounts routes
- FastAPI app → Card routes: mounts routes
- FastAPI app → Income routes: mounts routes
- FastAPI app → Expense routes: mounts routes
- FastAPI app → Pluggy access: mounts routes
- FastAPI app → Bank accounts and transactions: mounts routes
- User routes → JWT library: validates tokens
- Address routes → JWT library: validates tokens
- Card routes → JWT library: validates tokens
- Income routes → JWT library: validates tokens
- Expense routes → JWT library: validates tokens
- Pluggy access → JWT library: validates tokens
- Bank accounts and transactions → JWT library: validates tokens
- Token helper → JWT library: encodes and decodes
- Card routes → Request schemas: uses schemas
- Income routes → Request schemas: uses schemas
- Expense routes → Request schemas: uses schemas
- Pluggy access → Request schemas: uses token schema
- Bank accounts and transactions → Pluggy access: gets API key
- Bank accounts and transactions → Pluggy schemas: validates responses
- Pluggy access → Pluggy API: requests access and connectors
- Bank accounts and transactions → Pluggy API: fetches bank data
- User routes → SQLAlchemy sessions: opens sessions
- Address routes → SQLAlchemy sessions: opens sessions
- Card routes → SQLAlchemy sessions: opens sessions
- Income routes → SQLAlchemy sessions: opens sessions
- Expense routes → SQLAlchemy sessions: opens sessions
- Pluggy access → SQLAlchemy sessions: opens sessions
- Bank accounts and transactions → SQLAlchemy sessions: opens sessions
- SQLAlchemy sessions → MySQL database: connects to
- Card routes → ORM models: queries and updates
- Income routes → ORM models: queries and updates
- Expense routes → ORM models: queries and updates
- Pluggy access → ORM models: saves account link
- Bank accounts and transactions → ORM models: reads and updates link
- ORM models → MySQL database: maps stored records