# iuryhirabara/carbon architecture

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

- Interactive diagram: https://gitdiagram.com/iuryhirabara/carbon
- Repository: https://github.com/iuryhirabara/carbon

## Overview

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: [`src/views/pages`](https://github.com/iuryhirabara/carbon/tree/main/src/views/pages) (EJS Pages), [`src/routes/index.js`](https://github.com/iuryhirabara/carbon/blob/main/src/routes/index.js) (Routes), [`src/controllers/ParticipanteController.js`](https://github.com/iuryhirabara/carbon/blob/main/src/controllers/ParticipanteController.js) (Participant Ctrl), [`src/controllers/EstatisticasController.js`](https://github.com/iuryhirabara/carbon/blob/main/src/controllers/EstatisticasController.js) (Stats Ctrl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser"]
  node_views_pages["EJS Pages<br/>server views"]
  node_views_partials["Partials<br/>shared templates"]
  node_graficos_js["Charts JS<br/>browser script<br/>[graficos.js]"]
end

subgraph group_app["Node/Express App"]
  node_server["Server<br/>Express bootstrap<br/>[server.js]"]
  node_routes["Routes<br/>request router<br/>[index.js]"]
  node_participante_controller["Participant Ctrl<br/>controller"]
  node_estatisticas_controller["Stats Ctrl<br/>controller"]
  node_validation["Validation<br/>middleware"]
  node_calculadora["Calculator<br/>domain logic<br/>[calculadora.js]"]
  node_fatores_emissao["Emission Factors<br/>domain data<br/>[fatoresEmissao.js]"]
  node_participante_model["Participant Model<br/>data model"]
  node_db_config["DB Config<br/>sqlserver config<br/>[db.js]"]
end

subgraph group_data["SQL Server"]
  node_schema[("Database Schema<br/>sql schema<br/>[database.sql]")]
  node_sql_server[("SQL Server<br/>database")]
end

subgraph group_tooling["Tooling"]
  node_docker_compose["Docker Compose<br/>local infra<br/>[docker-compose.yml]"]
  node_workflow["CI Workflow<br/>automation<br/>[main_carbon.yml]"]
end

node_server -->|"mounts"| node_routes
node_server -->|"serves"| node_views_pages
node_routes -->|"guards"| node_validation
node_routes -->|"dispatches"| node_participante_controller
node_routes -->|"dispatches"| node_estatisticas_controller
node_participante_controller -->|"uses"| node_calculadora
node_participante_controller -->|"persists"| node_participante_model
node_estatisticas_controller -->|"reads"| node_participante_model
node_calculadora -->|"depends on"| node_fatores_emissao
node_participante_model -->|"connects via"| node_db_config
node_db_config -->|"connects to"| node_sql_server
node_schema -->|"defines"| node_sql_server
node_participante_controller -->|"renders"| node_views_pages
node_estatisticas_controller -->|"renders"| node_views_pages
node_views_pages -->|"composes"| node_views_partials
node_views_pages -->|"embeds"| node_graficos_js
node_graficos_js -->|"consumes data from"| node_views_pages
node_docker_compose -->|"provisions"| node_sql_server
node_workflow -.->|"checks"| node_server

click node_server "https://github.com/iuryhirabara/carbon/blob/main/src/server.js"
click node_routes "https://github.com/iuryhirabara/carbon/blob/main/src/routes/index.js"
click node_participante_controller "https://github.com/iuryhirabara/carbon/blob/main/src/controllers/ParticipanteController.js"
click node_estatisticas_controller "https://github.com/iuryhirabara/carbon/blob/main/src/controllers/EstatisticasController.js"
click node_validation "https://github.com/iuryhirabara/carbon/blob/main/src/middlewares/validacaoMiddleware.js"
click node_calculadora "https://github.com/iuryhirabara/carbon/blob/main/src/utils/calculadora.js"
click node_fatores_emissao "https://github.com/iuryhirabara/carbon/blob/main/src/utils/fatoresEmissao.js"
click node_participante_model "https://github.com/iuryhirabara/carbon/blob/main/src/models/ParticipanteModel.js"
click node_db_config "https://github.com/iuryhirabara/carbon/blob/main/src/config/db.js"
click node_views_pages "https://github.com/iuryhirabara/carbon/tree/main/src/views/pages"
click node_views_partials "https://github.com/iuryhirabara/carbon/tree/main/src/views/partials"
click node_graficos_js "https://github.com/iuryhirabara/carbon/blob/main/src/public/js/graficos.js"
click node_schema "https://github.com/iuryhirabara/carbon/blob/main/database.sql"
click node_docker_compose "https://github.com/iuryhirabara/carbon/blob/main/docker-compose.yml"
click node_workflow "https://github.com/iuryhirabara/carbon/blob/main/.github/workflows/main_carbon.yml"

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_views_pages,node_views_partials,node_graficos_js toneBlue
class node_server,node_routes,node_participante_controller,node_estatisticas_controller,node_validation,node_calculadora,node_fatores_emissao,node_participante_model,node_db_config toneAmber
class node_schema,node_sql_server toneMint
class node_docker_compose,node_workflow toneRose
```

## Components

### Browser

Server-rendered pages and client-side charting

- [EJS Pages](https://github.com/iuryhirabara/carbon/tree/main/src/views/pages): server views · Rendered pages for landing, questionnaire, result, statistics, login, and terms · `src/views/pages`
- [Partials](https://github.com/iuryhirabara/carbon/tree/main/src/views/partials): shared templates · Reusable header, head, and footer fragments · `src/views/partials`
- [Charts JS](https://github.com/iuryhirabara/carbon/blob/main/src/public/js/graficos.js): browser script · Client-side chart rendering for statistics pages · `src/public/js/graficos.js`

### Node/Express App

HTTP entrypoint, routing, controllers, domain logic, and persistence access

- [Server](https://github.com/iuryhirabara/carbon/blob/main/src/server.js): Express bootstrap · Starts the HTTP server and wires middleware, static assets, and routes · `src/server.js`
- [Routes](https://github.com/iuryhirabara/carbon/blob/main/src/routes/index.js): request router · Main dispatcher from HTTP requests to controller actions · `src/routes/index.js`
- [Participant Ctrl](https://github.com/iuryhirabara/carbon/blob/main/src/controllers/ParticipanteController.js): controller · Handles questionnaire flow, submission, and participant-facing pages · `src/controllers/ParticipanteController.js`
- [Stats Ctrl](https://github.com/iuryhirabara/carbon/blob/main/src/controllers/EstatisticasController.js): controller · Serves analytics and statistics pages · `src/controllers/EstatisticasController.js`
- [Validation](https://github.com/iuryhirabara/carbon/blob/main/src/middlewares/validacaoMiddleware.js): middleware · Validates incoming form data before controller logic · `src/middlewares/validacaoMiddleware.js`
- [Calculator](https://github.com/iuryhirabara/carbon/blob/main/src/utils/calculadora.js): domain logic · Core footprint calculation formulas · `src/utils/calculadora.js`
- [Emission Factors](https://github.com/iuryhirabara/carbon/blob/main/src/utils/fatoresEmissao.js): domain data · Emission factor rules used by the calculator · `src/utils/fatoresEmissao.js`
- [Participant Model](https://github.com/iuryhirabara/carbon/blob/main/src/models/ParticipanteModel.js): data model · Encapsulates participant reads, inserts, and aggregates · `src/models/ParticipanteModel.js`
- [DB Config](https://github.com/iuryhirabara/carbon/blob/main/src/config/db.js): sqlserver config · Central SQL Server connection setup · `src/config/db.js`

### SQL Server

Database schema and stored participant data

- [Database Schema](https://github.com/iuryhirabara/carbon/blob/main/database.sql): sql schema · SQL Server schema and seed structure · `database.sql`
- **SQL Server**: database · Persistent storage for participants and aggregates

### Tooling

Local setup and CI automation

- [Docker Compose](https://github.com/iuryhirabara/carbon/blob/main/docker-compose.yml): local infra · Convenience setup for running SQL Server locally · `docker-compose.yml`
- [CI Workflow](https://github.com/iuryhirabara/carbon/blob/main/.github/workflows/main_carbon.yml): automation · GitHub Actions pipeline for repository automation · `.github/workflows/main_carbon.yml`

## Connections

- 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
