# matheus-nbx52/ecoleta architecture

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

- Interactive diagram: https://gitdiagram.com/matheus-nbx52/ecoleta
- Repository: https://github.com/matheus-nbx52/ecoleta

## Overview

eColeta is a web platform for on-demand recyclable pickup, connecting residents, collectors, and cooperatives. Its core workflow is: users register and log in; a resident requests a pickup with scheduled time and waste items; a collector accepts it, transports it, and delivers it to a cooperative; the cooperative validates the weight, finalizing the pickup and awarding resident points. Dashboards and histories support each role, alongside waste guidance and account/profile features. The excerpts show the collection API and persistence flow; other capabilities are included where documented or visible in the tree, without asserting unsampled wiring.

Main entry points: [`backend/src/config/database.ts`](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/config/database.ts) (Database setup), [`backend/src/services/ColetaService.ts`](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/services/ColetaService.ts) (Pickup service), [`backend/src/services/AuthService.ts`](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/services/AuthService.ts) (Auth service), [`backend/src/routes/ColetaRoutes.ts`](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/routes/ColetaRoutes.ts) (Pickup routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_web_routes["Web routes<br/>[AppRoutes.tsx]"]
  node_auth_context["Auth context<br/>[AuthContext.tsx]"]
  node_resident_ui["Resident screens"]
  node_collector_ui["Collector dashboard"]
  node_coop_ui["Cooperative dashboard"]
  node_guidance["Waste guidance<br/>[Guiaseparacao.tsx]"]
  node_frontend_api["API client<br/>[api.ts]"]
  node_pickup_client["Pickup client<br/>[coletasService.ts]"]
end

subgraph group_api["API and access"]
  node_server["HTTP server<br/>[server.ts]"]
  node_auth_routes["Auth routes<br/>[AuthRoutes.ts]"]
  node_auth_controller["Auth controller<br/>[AuthController.ts]"]
  node_auth_service["Auth service<br/>[AuthService.ts]"]
  node_collection_routes["Pickup routes<br/>[ColetaRoutes.ts]"]
  node_collection_controller["Pickup controller"]
  node_auth_middleware["Authentication<br/>[AuthMiddleware.ts]"]
  node_role_middleware["Role checks<br/>[RoleMiddleware.ts]"]
end

subgraph group_logistics["Pickup logistics"]
  node_collection_service["Pickup service<br/>[ColetaService.ts]"]
end

subgraph group_domain["Domain and persistence"]
  node_pickup_model[("Pickup records<br/>[ColetaModel.ts]")]
  node_item_model[("Pickup items<br/>[ItemColetaModel.ts]")]
  node_waste_model[("Waste types<br/>[ResiduoModel.ts]")]
  node_resident_model[("Resident records<br/>[MoradorModel.ts]")]
  node_collector_model[("Collector records<br/>[EcoletorModel.ts]")]
  node_coop_model[("Cooperative records")]
  node_transaction_model[("Rewards transactions<br/>[TransacaoModel.ts]")]
  node_review_model[("Service reviews<br/>[AvaliacaoModel.ts]")]
  node_address_model[("Addresses<br/>[EnderecoModel.ts]")]
  node_database_config["Database setup<br/>[database.ts]"]
end

node_resident(("Resident"))
node_collector(("Collector"))
node_cooperative(("Cooperative"))
node_database[("Relational database")]

node_resident -->|"uses"| node_web_routes
node_collector -->|"uses"| node_web_routes
node_cooperative -->|"uses"| node_web_routes
node_web_routes -->|"provides auth"| node_auth_context
node_resident_ui -->|"requests pickups"| node_pickup_client
node_collector_ui -->|"manages pickups"| node_pickup_client
node_coop_ui -->|"validates pickups"| node_pickup_client
node_pickup_client -->|"sends requests"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_server
node_guidance -->|"guides sorting"| node_resident
node_server -->|"dispatches"| node_auth_routes
node_server -->|"dispatches"| node_collection_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"calls"| node_auth_service
node_auth_service -->|"checks credentials"| node_resident_model
node_auth_service -->|"checks credentials"| node_collector_model
node_auth_service -->|"checks credentials"| node_coop_model
node_collection_routes -->|"authenticates"| node_auth_middleware
node_collection_routes -->|"checks role"| node_role_middleware
node_collection_routes -->|"dispatches"| node_collection_controller
node_collection_controller -->|"calls"| node_collection_service
node_collection_service -->|"reads and writes"| node_pickup_model
node_collection_service -->|"saves items"| node_item_model
node_collection_service -->|"looks up types"| node_waste_model
node_collection_service -->|"updates points"| node_resident_model
node_collection_service -->|"assigns collector"| node_collector_model
node_collection_service -->|"assigns destination"| node_coop_model
node_database_config -->|"initializes"| node_database
node_database_config -->|"registers entities"| node_pickup_model
node_database_config -->|"registers entities"| node_item_model
node_database_config -->|"registers entities"| node_waste_model
node_database_config -->|"registers entities"| node_resident_model
node_database_config -->|"registers entities"| node_collector_model
node_database_config -->|"registers entities"| node_coop_model
node_database_config -->|"registers entities"| node_transaction_model
node_database_config -->|"registers entities"| node_review_model
node_database_config -->|"registers entities"| node_address_model

click node_web_routes "https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/routes/AppRoutes.tsx"
click node_auth_context "https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_resident_ui "https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/pages/dashboard/morador/DashboardMorador.tsx"
click node_collector_ui "https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/pages/dashboard/coletor/DashboardColetor.tsx"
click node_coop_ui "https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/pages/dashboard/cooperativa/DashboardCooperativa.tsx"
click node_guidance "https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/pages/guia-separacao/Guiaseparacao.tsx"
click node_frontend_api "https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/services/api.ts"
click node_pickup_client "https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/services/coletasService.ts"
click node_server "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/server.ts"
click node_auth_routes "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/routes/AuthRoutes.ts"
click node_auth_controller "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/controllers/AuthController.ts"
click node_auth_service "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/services/AuthService.ts"
click node_collection_routes "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/routes/ColetaRoutes.ts"
click node_collection_controller "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/controllers/ColetaController.ts"
click node_auth_middleware "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/middlewares/AuthMiddleware.ts"
click node_role_middleware "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/middlewares/RoleMiddleware.ts"
click node_collection_service "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/services/ColetaService.ts"
click node_pickup_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/ColetaModel.ts"
click node_item_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/ItemColetaModel.ts"
click node_waste_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/ResiduoModel.ts"
click node_resident_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/MoradorModel.ts"
click node_collector_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/EcoletorModel.ts"
click node_coop_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/CooperativaModel.ts"
click node_transaction_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/TransacaoModel.ts"
click node_review_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/AvaliacaoModel.ts"
click node_address_model "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/EnderecoModel.ts"
click node_database_config "https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/config/database.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_web_routes,node_auth_context,node_resident_ui,node_collector_ui,node_coop_ui,node_guidance,node_frontend_api,node_pickup_client toneBlue
class node_server,node_auth_routes,node_auth_controller,node_auth_service,node_collection_routes,node_collection_controller,node_auth_middleware,node_role_middleware,node_database toneAmber
class node_collection_service toneMint
class node_pickup_model,node_item_model,node_waste_model,node_resident_model,node_collector_model,node_coop_model,node_transaction_model,node_review_model,node_address_model,node_database_config toneRose
class node_resident,node_collector,node_cooperative toneIndigo
```

## Components

### Web experience

- [Web routes](https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/routes/AppRoutes.tsx): `frontend/src/routes/AppRoutes.tsx`
- [Auth context](https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/contexts/AuthContext.tsx): `frontend/src/contexts/AuthContext.tsx`
- [Resident screens](https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/pages/dashboard/morador/DashboardMorador.tsx): `frontend/src/pages/dashboard/morador/DashboardMorador.tsx`
- [Collector dashboard](https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/pages/dashboard/coletor/DashboardColetor.tsx): `frontend/src/pages/dashboard/coletor/DashboardColetor.tsx`
- [Cooperative dashboard](https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/pages/dashboard/cooperativa/DashboardCooperativa.tsx): `frontend/src/pages/dashboard/cooperativa/DashboardCooperativa.tsx`
- [Waste guidance](https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/pages/guia-separacao/Guiaseparacao.tsx): `frontend/src/pages/guia-separacao/Guiaseparacao.tsx`
- [API client](https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Pickup client](https://github.com/matheus-nbx52/ecoleta/blob/main/frontend/src/services/coletasService.ts): `frontend/src/services/coletasService.ts`

### API and access

- [HTTP server](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/server.ts): `backend/src/server.ts`
- [Auth routes](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/routes/AuthRoutes.ts): `backend/src/routes/AuthRoutes.ts`
- [Auth controller](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/controllers/AuthController.ts): `backend/src/controllers/AuthController.ts`
- [Auth service](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/services/AuthService.ts): `backend/src/services/AuthService.ts`
- [Pickup routes](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/routes/ColetaRoutes.ts): `backend/src/routes/ColetaRoutes.ts`
- [Pickup controller](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/controllers/ColetaController.ts): `backend/src/controllers/ColetaController.ts`
- [Authentication](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/middlewares/AuthMiddleware.ts): `backend/src/middlewares/AuthMiddleware.ts`
- [Role checks](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/middlewares/RoleMiddleware.ts): `backend/src/middlewares/RoleMiddleware.ts`

### Pickup logistics

- [Pickup service](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/services/ColetaService.ts): `backend/src/services/ColetaService.ts`

### Domain and persistence

- [Pickup records](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/ColetaModel.ts): `backend/src/models/ColetaModel.ts`
- [Pickup items](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/ItemColetaModel.ts): `backend/src/models/ItemColetaModel.ts`
- [Waste types](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/ResiduoModel.ts): `backend/src/models/ResiduoModel.ts`
- [Resident records](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/MoradorModel.ts): `backend/src/models/MoradorModel.ts`
- [Collector records](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/EcoletorModel.ts): `backend/src/models/EcoletorModel.ts`
- [Cooperative records](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/CooperativaModel.ts): `backend/src/models/CooperativaModel.ts`
- [Rewards transactions](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/TransacaoModel.ts): `backend/src/models/TransacaoModel.ts`
- [Service reviews](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/AvaliacaoModel.ts): `backend/src/models/AvaliacaoModel.ts`
- [Addresses](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/models/EnderecoModel.ts): `backend/src/models/EnderecoModel.ts`
- [Database setup](https://github.com/matheus-nbx52/ecoleta/blob/main/backend/src/config/database.ts): `backend/src/config/database.ts`

### Other components

- **Resident**
- **Collector**
- **Cooperative**
- **Relational database**

## Connections

- Resident → Web routes: uses
- Collector → Web routes: uses
- Cooperative → Web routes: uses
- Web routes → Auth context: provides auth
- Resident screens → Pickup client: requests pickups
- Collector dashboard → Pickup client: manages pickups
- Cooperative dashboard → Pickup client: validates pickups
- Pickup client → API client: sends requests
- API client → HTTP server: HTTP requests
- Waste guidance → Resident: guides sorting
- HTTP server → Auth routes: dispatches
- HTTP server → Pickup routes: dispatches
- Auth routes → Auth controller: dispatches
- Auth controller → Auth service: calls
- Auth service → Resident records: checks credentials
- Auth service → Collector records: checks credentials
- Auth service → Cooperative records: checks credentials
- Pickup routes → Authentication: authenticates
- Pickup routes → Role checks: checks role
- Pickup routes → Pickup controller: dispatches
- Pickup controller → Pickup service: calls
- Pickup service → Pickup records: reads and writes
- Pickup service → Pickup items: saves items
- Pickup service → Waste types: looks up types
- Pickup service → Resident records: updates points
- Pickup service → Collector records: assigns collector
- Pickup service → Cooperative records: assigns destination
- Database setup → Relational database: initializes
- Database setup → Pickup records: registers entities
- Database setup → Pickup items: registers entities
- Database setup → Waste types: registers entities
- Database setup → Resident records: registers entities
- Database setup → Collector records: registers entities
- Database setup → Cooperative records: registers entities
- Database setup → Rewards transactions: registers entities
- Database setup → Service reviews: registers entities
- Database setup → Addresses: registers entities