# arojaspolanco/supplier-management-api architecture

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

- Interactive diagram: https://gitdiagram.com/arojaspolanco/supplier-management-api
- Repository: https://github.com/arojaspolanco/supplier-management-api

## Overview

1. This repository is a Node.js backend organized as a feature-modular HTTP API. The entrypoints are `src/index.js` and `src/app.js`, with top-level routing assembled in `src/routes/routes.js`.

2. The codebase is split by business domain rather than by technical layer. The main domain modules are:
   - `Supplier`
   - `TaxInformation`
   - `CommercialCriteria`
   - `HseqCriteria`
   - `SafetyCriteria`
   - `Offers`
   - `Quoatations`  
   Each module has its own controller, service, model, route, and schema files, and some include middleware for request checks.

3. The request flow is the standard API pipeline: route → middleware/schema validation → controller → service → model/database. Controllers handle HTTP concerns, services contain business logic, and models represent persistence objects.

4. Database access is centralized under `src/config/database`. `database.js` likely initializes the ORM connection, while `associations.js` defines relationships between the feature models. This suggests a relational data model with cross-entity links between suppliers, criteria, offers, and quotations.

5. The criteria modules are a distinct subsystem. The qualification-related utility files (`qualificationComercialResults.js`, `qualificationHseqCriteria.js`, `qualificationSafetyCriteria.js`, `qualificationTaxInformationResulst.js`) indicate that the application computes evaluation or scoring results across several criteria domains, probably aggregating supplier qualification outcomes.

6. `src/utils/` contains cross-cutting helpers used by multiple modules:
   - message catalogs for success/error text
   - email utilities in `nodemailes.js`
   - domain result helpers for qualification logic
   - error-message extraction helpers  
   This is the shared application layer, separate from feature-specific code.

7. External integrations are visible in `src/config/conections/axios.config.js`, `src/config/plugins/generate-JWT.js`, and `src/utils/nodemailes.js`. That points to outbound HTTP calls, JWT generation for auth/token workflows, and email delivery as part of the backend’s integration surface.

8. Error handling is centralized. The `src/errors` folder contains custom error classes, async wrapper middleware, and a dedicated error controller/model, which means exceptions are normalized at the framework boundary instead of being handled ad hoc in each feature.

9. Configuration is environment-driven. `src/config/enviroments/enviroments.js` and `env.templates` imply deployment-specific settings are loaded from environment variables, keeping secrets and environment endpoints outside the code.

10. The schema files in each module suggest input validation is first-class. These schemas likely define request payload structure and business constraints before data reaches controllers or services.

11. `src/common/utils/extractErrorData.js` and the shared message files indicate the app converts low-level validation/database failures into consistent API responses. That matters for the architecture diagram because it is a separate cross-cutting error/response normalization path.

12. `wp_users.json` appears to be an auxiliary data fixture or import artifact, not a core runtime component. It may support seeding, testing, or integration with an external user source.

13. Overall, the architecture is a layered backend with a shared infrastructure tier, feature-based domains, centralized persistence, and several cross-cutting services for validation, qualification logic, email, JWT, and error handling.

Main entry points: [`src/routes/routes.js`](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/routes/routes.js) (routes.js), [`src/config/database/database.js`](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/database/database.js) (Database), [`src/utils`](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/utils) (Utils), [`src/app.js`](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/app.js) (app.js)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entry & routing"]
  node_n_index["index.js<br/>bootstrap<br/>[index.js]"]
  node_n_app["app.js<br/>app composition<br/>[app.js]"]
  node_n_routes["routes.js<br/>router assembly<br/>[routes.js]"]
end

subgraph group_grp_domains["Feature domains"]
  node_n_supplier["Supplier"]
  node_n_tax["Tax Info<br/>tax domain"]
  node_n_comercial["Commercial<br/>criteria domain"]
  node_n_hseq["HSEQ<br/>criteria domain"]
  node_n_safety["Safety<br/>criteria domain"]
  node_n_offers["Offers<br/>offer domain"]
  node_n_quotes["Quotations<br/>quotation domain"]
end

subgraph group_grp_infra["Shared infrastructure"]
  node_n_db[("Database<br/>orm init<br/>[database.js]")]
  node_n_assoc["Associations<br/>model links<br/>[associations.js]"]
  node_n_env["Env config<br/>runtime config<br/>[enviroments.js]"]
  node_n_axios["HTTP client<br/>outbound integration<br/>[axios.config.js]"]
  node_n_jwt["JWT plugin<br/>token utility<br/>[generate-JWT.js]"]
  node_n_errors["Errors<br/>error boundary"]
  node_n_utils["Utils<br/>shared helpers"]
  node_n_email["Email<br/>notification utility<br/>[nodemailes.js]"]
end

node_n_index -->|"boots"| node_n_app
node_n_app -->|"mounts"| node_n_routes
node_n_routes -->|"routes"| node_n_supplier
node_n_routes -->|"routes"| node_n_tax
node_n_routes -->|"routes"| node_n_comercial
node_n_routes -->|"routes"| node_n_hseq
node_n_routes -->|"routes"| node_n_safety
node_n_routes -->|"routes"| node_n_offers
node_n_routes -->|"routes"| node_n_quotes
node_n_supplier -->|"persists via"| node_n_db
node_n_tax -->|"persists via"| node_n_db
node_n_comercial -->|"persists via"| node_n_db
node_n_hseq -->|"persists via"| node_n_db
node_n_safety -->|"persists via"| node_n_db
node_n_offers -->|"persists via"| node_n_db
node_n_quotes -->|"persists via"| node_n_db
node_n_db -->|"links"| node_n_assoc
node_n_supplier -.->|"uses"| node_n_utils
node_n_comercial -.->|"uses"| node_n_utils
node_n_hseq -.->|"uses"| node_n_utils
node_n_safety -.->|"uses"| node_n_utils
node_n_tax -.->|"uses"| node_n_utils
node_n_app -.->|"centralizes"| node_n_errors
node_n_routes -.->|"configures"| node_n_env
node_n_app -.->|"calls out"| node_n_axios
node_n_app -.->|"auth/token"| node_n_jwt
node_n_utils -.->|"includes"| node_n_email

click node_n_index "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/index.js"
click node_n_app "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/app.js"
click node_n_routes "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/routes/routes.js"
click node_n_supplier "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/Supplier"
click node_n_tax "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/TaxInformation"
click node_n_comercial "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/ComercialCriteria"
click node_n_hseq "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/HseqCriteria"
click node_n_safety "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/SafetyCriteria"
click node_n_offers "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/Offers"
click node_n_quotes "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/Quoatations"
click node_n_db "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/database/database.js"
click node_n_assoc "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/database/associations.js"
click node_n_env "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/enviroments/enviroments.js"
click node_n_axios "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/conections/axios.config.js"
click node_n_jwt "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/plugins/generate-JWT.js"
click node_n_errors "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/errors"
click node_n_utils "https://github.com/arojaspolanco/supplier-management-api/tree/main/src/utils"
click node_n_email "https://github.com/arojaspolanco/supplier-management-api/blob/main/src/utils/nodemailes.js"

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_n_index,node_n_app,node_n_routes toneBlue
class node_n_supplier,node_n_tax,node_n_comercial,node_n_hseq,node_n_safety,node_n_offers,node_n_quotes toneAmber
class node_n_db,node_n_assoc,node_n_env,node_n_axios,node_n_jwt,node_n_errors,node_n_utils,node_n_email toneMint
```

## Components

### Entry & routing

Process bootstrap and top-level route assembly.

- [index.js](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/index.js): bootstrap · Starts the server process. · `src/index.js`
- [app.js](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/app.js): app composition · Creates the HTTP app and wires middleware. · `src/app.js`
- [routes.js](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/routes/routes.js): router assembly · Mounts the feature routes under a single entry point. · `src/routes/routes.js`

### Feature domains

Business modules organized by supplier qualification and commercial workflows.

- [Supplier](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/Supplier): supplier domain · Supplier lifecycle and validation flow. · `src/modules/Supplier`
- [Tax Info](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/TaxInformation): tax domain · Tax-information capture and checks. · `src/modules/TaxInformation`
- [Commercial](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/ComercialCriteria): criteria domain · Commercial qualification rules and scoring. · `src/modules/ComercialCriteria`
- [HSEQ](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/HseqCriteria): criteria domain · Health, safety, environment, and quality qualification. · `src/modules/HseqCriteria`
- [Safety](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/SafetyCriteria): criteria domain · Safety qualification rules and scoring. · `src/modules/SafetyCriteria`
- [Offers](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/Offers): offer domain · Offer handling and persistence. · `src/modules/Offers`
- [Quotations](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/modules/Quoatations): quotation domain · Quotation handling and persistence. · `src/modules/Quoatations`

### Shared infrastructure

Database, config, error handling, and cross-cutting utilities.

- [Database](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/database/database.js): orm init · Initializes the relational datastore connection. · `src/config/database/database.js`
- [Associations](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/database/associations.js): model links · Defines relationships between feature models. · `src/config/database/associations.js`
- [Env config](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/enviroments/enviroments.js): runtime config · Loads environment-specific settings. · `src/config/enviroments/enviroments.js`
- [HTTP client](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/conections/axios.config.js): outbound integration · Configured axios client for external requests. · `src/config/conections/axios.config.js`
- [JWT plugin](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/config/plugins/generate-JWT.js): token utility · Generates JWTs for auth or token workflows. · `src/config/plugins/generate-JWT.js`
- [Errors](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/errors): error boundary · Custom errors, async wrapper, and error controller/model. · `src/errors`
- [Utils](https://github.com/arojaspolanco/supplier-management-api/tree/main/src/utils): shared helpers · Messages, qualification helpers, email, and error extraction utilities. · `src/utils`
- [Email](https://github.com/arojaspolanco/supplier-management-api/blob/main/src/utils/nodemailes.js): notification utility · Nodemailer-based outbound email delivery. · `src/utils/nodemailes.js`

## Connections

- index.js → app.js: boots · Server startup delegates to app composition.
- app.js → routes.js: mounts · The app installs the top-level router.
- routes.js → Supplier: routes · Registers supplier endpoints.
- routes.js → Tax Info: routes · Registers tax-information endpoints.
- routes.js → Commercial: routes · Registers commercial-criteria endpoints.
- routes.js → HSEQ: routes · Registers HSEQ criteria endpoints.
- routes.js → Safety: routes · Registers safety criteria endpoints.
- routes.js → Offers: routes · Registers offers endpoints.
- routes.js → Quotations: routes · Registers quotation endpoints.
- Supplier → Database: persists via · Supplier data is stored through the shared database layer.
- Tax Info → Database: persists via · Tax-information records use the shared database layer.
- Commercial → Database: persists via · Commercial criteria data uses the shared database layer.
- HSEQ → Database: persists via · HSEQ criteria data uses the shared database layer.
- Safety → Database: persists via · Safety criteria data uses the shared database layer.
- Offers → Database: persists via · Offers are stored through the shared database layer.
- Quotations → Database: persists via · Quotations are stored through the shared database layer.
- Database → Associations: links · Associations define cross-model relationships.
- Supplier → Utils: uses · Supplier flows share messages and validation helpers.
- Commercial → Utils: uses · Qualification calculations reuse shared helper logic.
- HSEQ → Utils: uses · Qualification calculations reuse shared helper logic.
- Safety → Utils: uses · Qualification calculations reuse shared helper logic.
- Tax Info → Utils: uses · Qualification calculations reuse shared helper logic.
- app.js → Errors: centralizes · The app boundary normalizes failures through shared error handling.
- routes.js → Env config: configures · Runtime behavior depends on environment settings.
- app.js → HTTP client: calls out · Some flows use the shared outbound HTTP client.
- app.js → JWT plugin: auth/token · Token generation supports authentication-related workflows.
- Utils → Email: includes · Email sending is part of the shared application utilities.
