# mrvalraven/greendash-core architecture

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

- Interactive diagram: https://gitdiagram.com/mrvalraven/greendash-core
- Repository: https://github.com/mrvalraven/greendash-core

## Overview

##### Project Type and Purpose
- This is a **backend API server** built on Node.js/TypeScript using Express (or a similar HTTP framework) and Drizzle ORM for SQL migrations/queries.
- Key features:
- Authentication module (login, signup, JWT)
- Mail module (sending transactional emails)
- AI module (calling external AI service)
- Database layer wired via Drizzle and raw SQL migrations

##### High‐Level Architectural Overview
a. Client / Consumer
b. HTTP Server (Express app)
c. Routing & Middlewares
d. Feature Modules (Authentication, Mail, AI)
e. Data Access Layer (DB schemas, Drizzle ORM)
f. External Services (SMTP/Email provider, AI API)
g. Relational Database

##### Detailed Component Breakdown
- HTTP Server
- src/app.ts – initializes Express, loads middleware, mounts routes
- routes.ts – defines route‐to‐controller mappings

- Middlewares
- validationMiddleware.ts – request payload validation
- authMiddleware.ts – JWT/session validation & user extraction

- Feature Modules (each under src/modules/*)
- Controllers (e.g., authentication.controller.ts)
- Config & Constants (e.g., authentication.config.ts, mail.constants.ts)
- Service/Methods Layers (e.g., authentication.methods.ts, mail.service.ts)
- Utils & Types

- Database Layer
- drizzle.config.ts – ORM configuration, connection settings
- drizzle/*.sql – raw migration scripts
- src/db/index.ts – DB connection factory
- src/db/schemas/*.ts – table schemas and helpers

- External Integrations
- Mail provider (SMTP or 3rd‐party SDK)
- AI provider (OpenAI, etc.)

##### Relationships & Data Flow
1. Client → HTTP Server (TCP/HTTP)
2. HTTP Server → Validation Middleware → Auth Middleware
3. Router → Specific Module Controller
4. Controller → Service/Method Layer
5. Service → Data Access Layer (Drizzle ORM / raw SQL) → Database
6. Service → External API (Mail or AI)
7. Service → Controller → HTTP Response → Client

##### Architectural Patterns & Principles
- **Layered (Onion) Architecture**: clear separation between transport, controllers, services, repositories, and external integrations.
- **Modular Monolith**: each feature lives in its own directory under src/modules.
- **Dependency Injection** (via config imports) for swapping mocks, environments, or providers.
- **Convention over Configuration**: migration files in drizzle/, schema definitions under src/db/schemas.

##### Final Checklist
- [ ] Group feature modules together, showing intra‐module layering
- [ ] Show DB migrations vs. runtime schema layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client / Consumer"]:::external
    App["App (src/app.ts)"]:::internal
    Routes["Routes (src/routes.ts)"]:::internal
    Validation["Validation Middleware"]:::middleware
    AuthM["Authentication Middleware"]:::middleware

    subgraph "Authentication Module"
        direction TB
        AuthController["Authentication Controller"]:::internal
        AuthService["Authentication Methods/Service"]:::internal
        AuthDB["Authentication Database Access"]:::internal
        AuthSchemas["authentication.schemas.ts"]:::internal
        AuthTypes["authentication.types.ts"]:::internal
        AuthUtils["authentication.utils.ts"]:::internal
        AuthConfig["authentication.config.ts"]:::internal
        AuthErrors["authentication.errors.ts"]:::internal
    end

    subgraph "Mail Module"
        direction TB
        MailService["Mail Service"]:::internal
        MailConfig["mail.config.ts"]:::internal
        MailConstants["mail.constants.ts"]:::internal
        MailTypes["mail.types.ts"]:::internal
        MailUtils["mail.utils.ts"]:::internal
    end

    subgraph "AI Module"
        direction TB
        AiController["AI Controller"]:::internal
    end

    subgraph "Database Layer"
        direction TB
        DrizzleConfig["Drizzle ORM Configuration"]:::internal
        subgraph "Raw Migrations"
            direction TB
            M1["0000_regular_mystique.sql"]:::internal
            M2["0001_true_captain_cross.sql"]:::internal
        end
        ConnFactory["DB Connection Factory"]:::internal
        SchemaHelpers["columns.helpers.ts"]:::internal
        UserSchema["users.sql.ts"]:::internal
    end

    ExternalMail["SMTP / Email Provider"]:::external
    ExternalAI["External AI API"]:::external
    Database["Relational Database"]:::database

    Client -->|"HTTP Request"| App
    App -->|"load routes"| Routes
    Routes -->|"validate request"| Validation
    Validation -->|"authenticate"| AuthM
    AuthM -->|"route to controller"| AuthController

    AuthController -->|"call service"| AuthService
    AuthService -->|"query/auth actions"| AuthDB
    AuthDB -->|"use schemas"| AuthSchemas
    AuthSchemas --> AuthTypes
    AuthSchemas --> AuthUtils
    AuthConfigsAndErrors -.-> AuthConfig
    AuthConfigsAndErrors -.-> AuthErrors

    AuthService -->|"send email"| MailService
    MailService -->|"use config/constants"| MailConfig
    MailService --> MailConstants
    MailService --> MailTypes
    MailService --> MailUtils
    MailService -->|"SMTP call"| ExternalMail

    AuthController -->|"ai request"| AiController
    AiController -->|"external API call"| ExternalAI

    AuthService -->|"DB connect"| ConnFactory
    ConnFactory --> DrizzleConfig
    DrizzleConfig --> M1
    DrizzleConfig --> M2
    ConnFactory --> SchemaHelpers
    SchemaHelpers --> UserSchema
    UserSchema --> Database
    AuthDB --> Database

    click App "https://github.com/mrvalraven/greendash-core/blob/main/src/app.ts"
    click Routes "https://github.com/mrvalraven/greendash-core/blob/main/src/routes.ts"
    click Validation "https://github.com/mrvalraven/greendash-core/blob/main/src/middlewares/validationMiddleware.ts"
    click AuthM "https://github.com/mrvalraven/greendash-core/blob/main/src/middlewares/authMiddleware.ts"
    click AuthController "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/authentication/authentication.controller.ts"
    click AuthService "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/authentication/authentication.methods.ts"
    click AuthDB "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/authentication/authentication.database.ts"
    click AuthSchemas "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/authentication/authentication.schemas.ts"
    click AuthTypes "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/authentication/authentication.types.ts"
    click AuthUtils "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/authentication/authentication.utils.ts"
    click AuthConfig "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/authentication/authentication.config.ts"
    click AuthErrors "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/authentication/authentication.errors.ts"
    click MailService "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/mail/mail.service.ts"
    click MailConfig "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/mail/mail.config.ts"
    click MailConstants "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/mail/mail.constants.ts"
    click MailTypes "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/mail/mail.types.ts"
    click MailUtils "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/mail/mail.utils.ts"
    click AiController "https://github.com/mrvalraven/greendash-core/blob/main/src/modules/ai/ai.controller.ts"
    click DrizzleConfig "https://github.com/mrvalraven/greendash-core/blob/main/drizzle.config.ts"
    click M1 "https://github.com/mrvalraven/greendash-core/blob/main/drizzle/0000_regular_mystique.sql"
    click M2 "https://github.com/mrvalraven/greendash-core/blob/main/drizzle/0001_true_captain_cross.sql"
    click ConnFactory "https://github.com/mrvalraven/greendash-core/blob/main/src/db/index.ts"
    click SchemaHelpers "https://github.com/mrvalraven/greendash-core/blob/main/src/db/schemas/columns.helpers.ts"
    click UserSchema "https://github.com/mrvalraven/greendash-core/blob/main/src/db/schemas/users.sql.ts"

    classDef internal fill:#AED6F1,stroke:#2E86C1,color:#1B4F72;
    classDef middleware fill:#D7BDE2,stroke:#7D3C98,color:#4A235A;
    classDef database fill:#ABEBC6,stroke:#27AE60,color:#1D8348;
    classDef external fill:#F5CBA7,stroke:#E67E22,color:#873600;
```
