# addielfs/ecocycle architecture

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

- Interactive diagram: https://gitdiagram.com/addielfs/ecocycle
- Repository: https://github.com/addielfs/ecocycle

## Overview

1. **System shape**
   - EcoCycle is split into two runnable applications plus three backend layers:
     - **EcoCycle.API**: REST API host.
     - **EcoCycle.Web**: MVC/Razor frontend.
     - **EcoCycle.Application / Domain / Infrastructure**: shared backend architecture used by the API.
   - The solution is a **clean-architecture-style separation** with controller → service → repository → database flow.

2. **Primary request path**
   - Client requests hit either the **API controllers** or the **MVC web controllers**.
   - The API controllers are the core business entry point for data operations.
   - The Web project acts as a separate presentation client that calls the API through an internal **ApiService** rather than accessing the database directly.

3. **API host responsibilities**
   - `EcoCycle.API` contains the REST controllers, global exception middleware, startup configuration, and Swagger/OpenAPI exposure.
   - It is the boundary for authentication, authorization, and HTTP-level validation/error handling.
   - The API also hosts endpoints for image upload/delete flows tied to publications.

4. **Application layer**
   - `EcoCycle.Application` contains the use-case logic:
     - DTOs for request/response shaping.
     - Service implementations for the main business capabilities.
     - FluentValidation validators for input rules.
   - This layer depends on domain abstractions, not on EF Core or HTTP.

5. **Domain layer**
   - `EcoCycle.Domain` defines the core business model:
     - Entities such as `Usuario`, `Material`, `Publicacion`, `CentroReciclaje`, `Recompensa`, and `Configuracion`.
     - Repository interfaces for persistence contracts.
   - This is the main business boundary and contains no infrastructure concerns.

6. **Infrastructure layer**
   - `EcoCycle.Infrastructure` provides the technical implementation:
     - `AppDbContext` and EF Core entity configurations.
     - Repository implementations for each aggregate.
     - Database migrations and model snapshot.
     - Seed data initialization.
     - Local image storage service implementation.
   - This is where the system touches SQL Server and the filesystem.

7. **Persistence and database flow**
   - Data is persisted in **SQL Server** via **Entity Framework Core Code First**.
   - The migration history shows schema evolution for role/configuration and geolocation fields.
   - Repositories abstract persistence for the application layer, while EF Core configurations define table/column mapping.

8. **Authentication and authorization**
   - The system uses **JWT** with roles.
   - Roles drive major boundaries:
     - **Admin**: manages materials, centers, rewards, configuration, and reports.
     - **Usuario**: can manage own publications and access dashboard features.
   - Ownership checks are important for publications: the backend assigns `IdUsuario` from the JWT rather than trusting the client.

9. **Main business subsystems**
   - **Materials**: catalog of recyclable materials.
   - **Publications**: user-created recycling posts, with material association, location, and image.
   - **Recycling centers**: managed locations with map coordinates.
   - **Rewards**: points accumulation and reward management.
   - **Configuration**: admin-editable settings such as conversion factor.
   - **Reports**: aggregate/admin-only read models like most-published materials and points by user.

10. **Image handling**
   - Publication images are stored locally under `wwwroot/uploads/` via the infrastructure image storage service.
   - The system enforces file-type/size rules and generates unique filenames.
   - This is a filesystem boundary, not an external blob service.

11. **Frontend architecture**
   - `EcoCycle.Web` is an ASP.NET Core MVC app with Razor views and Bootstrap.
   - It contains page controllers, view models, and UI templates for login, dashboard, CRUD screens, and reports.
   - The frontend reads from the API through `ApiService`, so the browser-facing app and the backend API are intentionally separated.

12. **Map and geolocation**
   - Publications and recycling centers include location data rendered with **Leaflet** and **OpenStreetMap**.
   - The map is part of the UI for selecting and visualizing coordinates; it affects both create/edit flows and display flows.

13. **Cross-cutting concerns**
   - `ExceptionMiddleware` centralizes API error handling.
   - Validators provide input protection before business logic runs.
   - Swagger is used for API discoverability and interactive testing.

14. **Startup and initialization**
   - The API startup wires together all layers via dependency injection registrations.
   - On first run, the app seeds initial domain data such as materials, an admin user, and default conversion settings.
   - Database schema changes are managed through EF Core migrations, not manual SQL scripts.

15. **Diagram takeaway**
   - The clearest architecture diagram should show:
     - **Web UI** and **API** as separate hosts.
     - API controllers calling **Application services**.
     - Services depending on **Domain interfaces/entities**.
     - **Infrastructure** implementing repositories, EF Core, seed data, and local file storage.
     - **SQL Server** and **filesystem uploads** as the two main persistence targets.

Main entry points: [`EcoCycle.Application/Services`](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Application/Services) (Use-Case Services), [`EcoCycle.API/Program.cs`](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Program.cs) (EcoCycle.API), [`EcoCycle.Infrastructure/Data/AppDbContext.cs`](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Data/AppDbContext.cs) (AppDbContext), [`EcoCycle.API/Controllers`](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Controllers) (API Controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["Hosts"]
  node_api_host["EcoCycle.API<br/>REST host<br/>[Program.cs]"]
  node_web_host["EcoCycle.Web<br/>MVC host<br/>[Program.cs]"]
  node_api_controllers["API Controllers<br/>HTTP endpoints<br/>[Controllers]"]
  node_api_middleware{{"Exception Middleware<br/>error handling"}}
  node_api_startup["API Startup<br/>DI/bootstrap<br/>[Program.cs]"]
end

subgraph group_application["Application Layer"]
  node_app_services["Use-Case Services<br/>business logic<br/>[Services]"]
  node_dto_layer["DTOs<br/>contracts<br/>[DTOs]"]
  node_validators["Validators<br/>input rules<br/>[Validators]"]
end

subgraph group_domain["Domain Model"]
  node_domain_entities[("Entities<br/>domain model<br/>[Entities]")]
  node_domain_repos["Repository Interfaces<br/>persistence contracts<br/>[Interfaces]"]
end

subgraph group_infrastructure["Infrastructure"]
  node_db_context[("AppDbContext<br/>EF Core context<br/>[AppDbContext.cs]")]
  node_ef_config["Entity Configs<br/>table mapping<br/>[Configurations]"]
  node_repositories["Repositories<br/>data access<br/>[Repositories]"]
  node_data_seeder["Data Seeder<br/>bootstrap data<br/>[DataSeeder.cs]"]
  node_image_storage["Image Storage<br/>filesystem service"]
  node_sql_server[("SQL Server<br/>database")]
  node_file_uploads["Uploads Folder<br/>filesystem<br/>[wwwroot]"]
end

subgraph group_webui["Web UI"]
  node_web_controllers["Web Controllers<br/>MVC pages<br/>[Controllers]"]
  node_api_service["ApiService<br/>API client<br/>[ApiService.cs]"]
  node_views["Razor Views<br/>UI templates<br/>[Views]"]
end

node_web_controllers -->|"uses"| node_api_service
node_api_service -->|"calls"| node_api_controllers
node_web_controllers -->|"renders"| node_views
node_api_host -->|"hosts"| node_api_controllers
node_api_host -->|"uses"| node_api_middleware
node_api_host -->|"configures"| node_api_startup
node_api_controllers -->|"calls"| node_app_services
node_app_services -->|"uses"| node_dto_layer
node_app_services -->|"checks"| node_validators
node_app_services -->|"depends on"| node_domain_entities
node_app_services -->|"depends on"| node_domain_repos
node_repositories -->|"implements"| node_domain_repos
node_repositories -->|"uses"| node_db_context
node_db_context -->|"maps"| node_ef_config
node_db_context -->|"persists to"| node_sql_server
node_data_seeder -->|"initializes"| node_db_context
node_image_storage -->|"writes"| node_file_uploads
node_app_services -->|"uses"| node_image_storage
node_api_host -.->|"connects"| node_sql_server
node_web_host -->|"depends on"| node_api_service

click node_api_host "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Program.cs"
click node_web_host "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/Program.cs"
click node_api_controllers "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Controllers"
click node_api_middleware "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Middleware/ExceptionMiddleware.cs"
click node_api_startup "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Program.cs"
click node_web_controllers "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/Controllers"
click node_api_service "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/Services/ApiService.cs"
click node_views "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/Views"
click node_app_services "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Application/Services"
click node_dto_layer "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Application/DTOs"
click node_validators "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Application/Validators"
click node_domain_entities "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Domain/Entities"
click node_domain_repos "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Domain/Interfaces"
click node_db_context "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Data/AppDbContext.cs"
click node_ef_config "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Data/Configurations"
click node_repositories "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Repositories"
click node_data_seeder "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Data/DataSeeder.cs"
click node_image_storage "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Services/ImageStorageService.cs"
click node_file_uploads "https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/wwwroot"

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_api_host,node_web_host,node_api_controllers,node_api_middleware,node_api_startup toneBlue
class node_app_services,node_dto_layer,node_validators toneAmber
class node_domain_entities,node_domain_repos toneMint
class node_db_context,node_ef_config,node_repositories,node_data_seeder,node_image_storage,node_sql_server,node_file_uploads toneRose
class node_web_controllers,node_api_service,node_views toneIndigo
```

## Components

### Hosts

Runnable ASP.NET Core applications exposed to users and clients.

- [EcoCycle.API](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Program.cs): REST host · REST API host with controllers, middleware, startup wiring, and Swagger. · `EcoCycle.API/Program.cs`
- [EcoCycle.Web](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/Program.cs): MVC host · Browser-facing MVC/Razor frontend that calls the API through a service layer. · `EcoCycle.Web/Program.cs`
- [API Controllers](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Controllers): HTTP endpoints · Business entry points for auth, materials, publications, centers, rewards, and reports. · `EcoCycle.API/Controllers`
- [Exception Middleware](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Middleware/ExceptionMiddleware.cs): error handling · Centralized API exception handling and HTTP error shaping. · `EcoCycle.API/Middleware/ExceptionMiddleware.cs`
- [API Startup](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.API/Program.cs): DI/bootstrap · Registers services, auth, Swagger, and other API host dependencies. · `EcoCycle.API/Program.cs`

### Application Layer

Use cases, DTOs, and validation for business workflows.

- [Use-Case Services](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Application/Services): business logic · Application services that orchestrate business workflows and persistence. · `EcoCycle.Application/Services`
- [DTOs](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Application/DTOs): contracts · Request and response shapes used across API and web flows. · `EcoCycle.Application/DTOs`
- [Validators](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Application/Validators): input rules · FluentValidation rules that guard inputs before business logic runs. · `EcoCycle.Application/Validators`

### Domain Model

Core entities and persistence contracts.

- [Entities](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Domain/Entities): domain model · Core business entities such as Usuario, Material, Publicacion, and Configuracion. · `EcoCycle.Domain/Entities`
- [Repository Interfaces](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Domain/Interfaces): persistence contracts · Abstractions for repository access used by the application layer. · `EcoCycle.Domain/Interfaces`

### Infrastructure

EF Core, repositories, seed data, and file storage implementations.

- [AppDbContext](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Data/AppDbContext.cs): EF Core context · EF Core unit of work and database mapping entry point. · `EcoCycle.Infrastructure/Data/AppDbContext.cs`
- [Entity Configs](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Data/Configurations): table mapping · EF Core entity configurations that define schema and relationships. · `EcoCycle.Infrastructure/Data/Configurations`
- [Repositories](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Repositories): data access · EF Core repository implementations for each aggregate. · `EcoCycle.Infrastructure/Repositories`
- [Data Seeder](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Data/DataSeeder.cs): bootstrap data · Initializes default materials, admin data, and configuration values. · `EcoCycle.Infrastructure/Data/DataSeeder.cs`
- [Image Storage](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Infrastructure/Services/ImageStorageService.cs): filesystem service · Stores publication images under local uploads in wwwroot. · `EcoCycle.Infrastructure/Services/ImageStorageService.cs`
- **SQL Server**: database · Primary relational persistence target via EF Core code-first migrations.
- [Uploads Folder](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/wwwroot): filesystem · Local filesystem boundary for stored publication images. · `EcoCycle.Web/wwwroot`

### Web UI

MVC presentation layer that consumes the API.

- [Web Controllers](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/Controllers): MVC pages · UI controllers for login, dashboard, CRUD screens, and reports. · `EcoCycle.Web/Controllers`
- [ApiService](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/Services/ApiService.cs): API client · Frontend integration service that calls the REST API instead of the database. · `EcoCycle.Web/Services/ApiService.cs`
- [Razor Views](https://github.com/addielfs/ecocycle/blob/main/EcoCycle.Web/Views): UI templates · Razor pages and layouts used for the web presentation layer. · `EcoCycle.Web/Views`

## Connections

- Web Controllers → ApiService: uses · Web pages invoke backend operations through the API client.
- ApiService → API Controllers: calls · HTTP requests are sent to the REST API controllers.
- Web Controllers → Razor Views: renders · MVC controllers select Razor views for presentation.
- EcoCycle.API → API Controllers: hosts · API host exposes the REST controllers.
- EcoCycle.API → Exception Middleware: uses · Startup wires the centralized error middleware.
- EcoCycle.API → API Startup: configures · Program bootstrap configures dependency injection and services.
- API Controllers → Use-Case Services: calls · Controllers delegate business workflows to application services.
- Use-Case Services → DTOs: uses · Services consume and return shaped DTOs.
- Use-Case Services → Validators: checks · Inputs are validated before workflow execution.
- Use-Case Services → Entities: depends on · Business logic is built around domain entities and rules.
- Use-Case Services → Repository Interfaces: depends on · Services rely on repository abstractions rather than EF Core directly.
- Repositories → Repository Interfaces: implements · Infrastructure fulfills repository contracts defined in the domain.
- Repositories → AppDbContext: uses · Repositories execute persistence through EF Core.
- AppDbContext → Entity Configs: maps · DbContext applies entity configurations.
- AppDbContext → SQL Server: persists to · EF Core stores application data in SQL Server.
- Data Seeder → AppDbContext: initializes · Seeder populates the database on startup or first run.
- Image Storage → Uploads Folder: writes · Publication images are saved to the local uploads folder.
- Use-Case Services → Image Storage: uses · Publication workflows delegate image file handling to infrastructure.
- EcoCycle.API → SQL Server: connects · The API ultimately reaches the SQL Server-backed persistence layer through services.
- EcoCycle.Web → ApiService: depends on · The web app is separated from persistence and depends on the API client.