How iuryhirabara/carbon works
1. Project shape
- EcoFootprint is a classic Node.js + Express application using a server-rendered MVC structure.
- The UI is mostly generated on the server with EJS, with a small amount of browser-side JavaScript for charts and visualizations.
2. Runtime and entry point
- The application starts in src/server.js, which is the HTTP server bootstrap.
- That entry point wires together Express, middleware, static assets, and the route table.
3. Routing boundary
- src/routes/index.js is the main request dispatcher.
- It connects browser requests to controller actions and acts as the boundary between HTTP concerns and application logic.
4. Controllers: the application layer
- src/controllers/ParticipanteController.js handles the participant-facing flow: questionnaire, result submission, and likely login/entry-related pages.
- src/controllers/EstatisticasController.js handles analytics/statistics pages.
- Controllers coordinate validation, calculations, persistence, and view rendering; they do not contain database SQL directly.
5. Domain logic and carbon calculation
- src/utils/calculadora.js and src/utils/fatoresEmissao.js hold the core business rules for carbon footprint computation.
- This is the main domain boundary: questionnaire answers are transformed into emissions estimates using emission factors and calculation formulas.
- Keeping this logic separate from controllers makes it reusable for both result generation and statistical analysis.
6. Persistence layer
- src/models/ParticipanteModel.js encapsulates database access for participant data.
- The model likely performs inserts, reads, and aggregate queries against Microsoft SQL Server.
- src/config/db.js centralizes the SQL Server connection setup, making database access a single infrastructure dependency.
7. Validation and request safety
- src/middlewares/validacaoMiddleware.js protects the application boundary by validating incoming form data before it reaches controller logic.
- The README mentions Helmet, CORS, express-rate-limit, and express-validator, so the request pipeline is designed with basic security and abuse protection in mind.
8. Server-rendered pages
- Views live under src/views/pages and are composed from shared partials in src/views/partials.
- Main pages include:
- index: landing page
- questionario: carbon footprint questionnaire
- resultado: computed footprint result
- estatisticas: aggregated analytics
- login and termos: supporting flows
- This is a multi-page app, not a SPA.
9. Client-side visualization
- src/public/js/graficos.js is the main browser-side script.
- It likely consumes data embedded by EJS and renders charts with Chart.js on the statistics page.
- This is the main frontend interaction beyond standard form submission.
10. Request/data flow for the questionnaire
- User submits the questionnaire from an EJS page.
- Validation middleware checks the payload.
- The participant controller invokes the calculation utilities.
- The model persists participant data in SQL Server.
- The result is rendered back to the browser in resultado.ejs.
11. Request/data flow for statistics
- The statistics controller retrieves participant data or aggregates from the model.
- The data is passed into estatisticas.ejs.
- graficos.js turns that server-provided data into charts in the browser.
12. Infrastructure and local setup
- The repository includes database.sql for schema creation and docker-compose.yml to simplify running SQL Server locally.
- Environment-specific settings are expected in .env, based on .env.example.
13. Operational/tooling boundary
- A GitHub Actions workflow exists under .github/workflows/main_carbon.yml, indicating CI automation is part of the repo.
- The app is otherwise fairly self-contained: one Node service, one SQL Server database, and static assets served by Express.
14. Architecture summary for a diagram
- Draw it as three main zones:
- Browser: EJS-rendered pages plus Chart.js/vanilla JS
- Node/Express app: routes → controllers → utilities/model → views
- SQL Server: participant storage and statistics source
- The key boundaries are HTTP routing, business calculation, and database persistence.
Main entry points: pages EJS Pages · index.js Routes · ParticipanteController.js Participant Ctrl · EstatisticasController.js Stats Ctrl
Components 16
Browser
Server-rendered pages and client-side charting
Node/Express App
HTTP entrypoint, routing, controllers, domain logic, and persistence access
- Server · Starts the HTTP server and wires middleware, static assets, and routes
src/server.js - Routes · Main dispatcher from HTTP requests to controller actions
src/routes/index.js - Participant Ctrl · Handles questionnaire flow, submission, and participant-facing pages
src/controllers/ParticipanteController.js - Stats Ctrl · Serves analytics and statistics pages
src/controllers/EstatisticasController.js - Validation · Validates incoming form data before controller logic
src/middlewares/validacaoMiddleware.js - Calculator · Core footprint calculation formulas
src/utils/calculadora.js - Emission Factors · Emission factor rules used by the calculator
src/utils/fatoresEmissao.js - Participant Model · Encapsulates participant reads, inserts, and aggregates
src/models/ParticipanteModel.js - DB Config · Central SQL Server connection setup
src/config/db.js
SQL Server
Database schema and stored participant data
- Database Schema · SQL Server schema and seed structure
database.sql - SQL Server · Persistent storage for participants and aggregates
Tooling
Local setup and CI automation
- Docker Compose · Convenience setup for running SQL Server locally
docker-compose.yml - CI Workflow · GitHub Actions pipeline for repository automation
.github/workflows/main_carbon.yml
Connections 19
- Server → Routes: mounts · Bootstraps request routing
- Server → EJS Pages: serves · Exposes rendered pages and static app output
- Routes → Validation: guards · Applies request validation before handlers
- Routes → Participant Ctrl: dispatches · Sends participant requests to controller actions
- Routes → Stats Ctrl: dispatches · Sends analytics requests to controller actions
- Participant Ctrl → Calculator: uses · Computes footprint results
- Participant Ctrl → Participant Model: persists · Stores and retrieves participant data
- Stats Ctrl → Participant Model: reads · Loads data or aggregates for statistics
- Calculator → Emission Factors: depends on · Uses emission factors in calculations
- Participant Model → DB Config: connects via · Uses shared SQL Server connection
- DB Config → SQL Server: connects to · Infrastructure database connection
- Database Schema → SQL Server: defines · Database structure for the runtime store
- Participant Ctrl → EJS Pages: renders · Returns questionnaire and result pages
- Stats Ctrl → EJS Pages: renders · Returns the statistics page
- EJS Pages → Partials: composes · Builds pages from shared template fragments
- EJS Pages → Charts JS: embeds · Provides data for browser-side chart rendering
- Charts JS → EJS Pages: consumes data from · Uses server-rendered data on the statistics page
- Docker Compose → SQL Server: provisions · Creates a local SQL Server runtime
- CI Workflow → Server: checks · Automated repository validation and build flow