# emmanuelnwankwo/env-core architecture

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

- Interactive diagram: https://gitdiagram.com/emmanuelnwankwo/env-core
- Repository: https://github.com/emmanuelnwankwo/env-core

## Overview

##### Main Components
a. Core Validation Engine – This is the heart of the library, likely implemented in functions (for example, the validateEnv function in src/index.ts) that accept a schema and then verify that the actual environment variables meet the expected types and rules.
b. Schema Definition & Parsing – Represents how developers define environment schemas (as seen in the provided usage examples) and how these definitions are parsed into internal representations (potentially expanded via the types defined in src/types.ts).
c. Error Handling Module – Illustrates the generation of descriptive error messages whenever validation fails. This component processes missing or type-mismatched variables.
e. Testing & CI/CD – While not a runtime component, the structure indicates that the project maintains tests (located in the test directory) and CI/CD workflows (in the .github/workflows folder). It’s useful to include these aspects as side components to show the development and quality assurance process.

##### Relationships and Interactions
- Client Applications (for example, an Express.js or NestJS application) import and call the validateEnv function at startup.
- The validateEnv function takes the schema (defined by the user) and either reads process.env or a specified .env file.
- The Validation Engine uses the Schema Parser to check each variable’s type and required attributes.
- Upon a validation error, the Error Handling module formats a detailed error message and throws an exception, preventing the app from running.
- In successful cases, the function returns a validated environment configuration object to be used by the client application.
- The CI/CD pipelines and testing frameworks ensure that all these interactions work correctly.

##### Architectural Patterns and Design Principles
- Modular Design: The library is kept as minimal as possible with separate concerns for configuration parsing, validation, and error handling.
- Type-Safety: By using TypeScript (as indicated by the tsconfig files and .ts source files) and defined types in src/types.ts, the library emphasizes robust type-checking.
- Build and Test Integration: The presence of ESLint, Jest, and GitHub workflows indicates that code quality and automated testing are integral to the development process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External and starting points
    ENV["Environment Variables (process.env/.env)"]:::external

    %% Client Integrations subgraph
    subgraph "Client Integrations"
        EXPR["Express Adapter"]:::external
        NEST["NestJS Adapter"]:::external
    end

    %% Internal Library Components subgraph
    subgraph "Internal Library Components"
        VALID["ValidateEnv Function (src/index.ts)"]:::internal
        SCHEMA["Schema Definition & Parsing (src/types.ts)"]:::internal
        ERROR["Error Handler (within src/index.ts)"]:::internal
        CONFIG["Validated Configuration"]:::internal
    end

    %% Development and Testing subgraph
    subgraph "Development & CI/CD"
        TEST["Testing Suite (test)"]:::test
        CICD["CI/CD Workflows (.github/workflows)"]:::cicd
    end

    %% Data Flows
    ENV -->|"input"| VALID
    EXPR -->|"invokes"| VALID
    NEST -->|"invokes"| VALID
    VALID -->|"parsesSchema"| SCHEMA
    VALID -->|"ifSuccess"| CONFIG
    VALID -->|"ifError"| ERROR
    CONFIG -->|"providedTo"| EXPR
    CONFIG -->|"providedTo"| NEST

    %% Development flows (dashed)
    TEST -.->|"verifies"| VALID
    CICD -.->|"triggers"| TEST

    %% Click Events
    click VALID "https://github.com/emmanuelnwankwo/env-core/blob/main/src/index.ts"
    click SCHEMA "https://github.com/emmanuelnwankwo/env-core/blob/main/src/types.ts"
    click TEST "https://github.com/emmanuelnwankwo/env-core/tree/main/test"
    click CICD "https://github.com/emmanuelnwankwo/env-core/tree/main/.github/workflows"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#000,stroke-width:2px;
    classDef external fill:#FFE0E0,stroke:#000,stroke-width:2px;
    classDef test fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef cicd fill:#FFFACD,stroke:#000,stroke-width:2px;
```
