How addielfs/ecocycle works
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: Services Use-Case Services · Program.cs EcoCycle.API · AppDbContext.cs AppDbContext · Controllers API Controllers
Components 20
Hosts
Runnable ASP.NET Core applications exposed to users and clients.
- EcoCycle.API · REST API host with controllers, middleware, startup wiring, and Swagger.
EcoCycle.API/Program.cs - EcoCycle.Web · Browser-facing MVC/Razor frontend that calls the API through a service layer.
EcoCycle.Web/Program.cs - API Controllers · Business entry points for auth, materials, publications, centers, rewards, and reports.
EcoCycle.API/Controllers - Exception Middleware · Centralized API exception handling and HTTP error shaping.
EcoCycle.API/Middleware/ExceptionMiddleware.cs - API Startup · 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 · Application services that orchestrate business workflows and persistence.
EcoCycle.Application/Services - DTOs · Request and response shapes used across API and web flows.
EcoCycle.Application/DTOs - Validators · FluentValidation rules that guard inputs before business logic runs.
EcoCycle.Application/Validators
Domain Model
Core entities and persistence contracts.
- Entities · Core business entities such as Usuario, Material, Publicacion, and Configuracion.
EcoCycle.Domain/Entities - Repository Interfaces · Abstractions for repository access used by the application layer.
EcoCycle.Domain/Interfaces
Infrastructure
EF Core, repositories, seed data, and file storage implementations.
- AppDbContext · EF Core unit of work and database mapping entry point.
EcoCycle.Infrastructure/Data/AppDbContext.cs - Entity Configs · EF Core entity configurations that define schema and relationships.
EcoCycle.Infrastructure/Data/Configurations - Repositories · EF Core repository implementations for each aggregate.
EcoCycle.Infrastructure/Repositories - Data Seeder · Initializes default materials, admin data, and configuration values.
EcoCycle.Infrastructure/Data/DataSeeder.cs - Image Storage · Stores publication images under local uploads in wwwroot.
EcoCycle.Infrastructure/Services/ImageStorageService.cs - SQL Server · Primary relational persistence target via EF Core code-first migrations.
- Uploads Folder · Local filesystem boundary for stored publication images.
EcoCycle.Web/wwwroot
Web UI
MVC presentation layer that consumes the API.
- Web Controllers · UI controllers for login, dashboard, CRUD screens, and reports.
EcoCycle.Web/Controllers - ApiService · Frontend integration service that calls the REST API instead of the database.
EcoCycle.Web/Services/ApiService.cs - Razor Views · Razor pages and layouts used for the web presentation layer.
EcoCycle.Web/Views
Connections 20
- 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.