# juliendargelos/deno-graphql-api architecture

> Architecture diagram of the GitHub repository juliendargelos/deno-graphql-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juliendargelos/deno-graphql-api
- Repository: https://github.com/juliendargelos/deno-graphql-api

## Overview

##### Project type and purpose
- This is a Deno‐based, modular GraphQL API template. It uses oak_graphql as the HTTP/GraphQL server and cotton as the ORM/migration tool. The goal is to let you drop in self‐contained “modules” (e.g., Article, User, Authentication) that each bring their own GraphQL types, resolvers, and data models.

##### File structure
- Top level:
- mod.ts — application entrypoint (boots Oak, cotton, loads modules)
- Dockerfile, .env, ormconfig.ts — containerization and DB config
- cache.ts, environment.ts, scripts.config.ts — runtime utilities and script hooks
- migrations/ — raw database migrations for cotton
- modules/
- core/ — autoloader, base Model, Module classes, shared resolvers and GraphQL types
- article/, user/, authentication/ — each defines its own GraphQL types.graphql, TypeScript model, resolvers, and exports via mod.ts
- Config files: importmap.json, lock.json, tsconfig.json

##### README for additional insights
- Outlines the “plugin” approach: each module exports models, resolvers, types
- Describes how cotton hooks models to DB tables, how oak_graphql uses the merged schema
- Highlights JWT authentication injected into the GraphQL context

##### Final recommendations
- Dynamic loading step prominently—this is the architectural heart of the template
- Migration workflow separately (cotton CLI → migrations folder → Database)
- Review the README’s “Scripts” section to add a “Dev Tools” cluster (denon, migrations, docker commands)

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Client
    Client["Client\n(GraphQL Queries/Mutations)"]:::external

    %% HTTP & GraphQL Server
    Server["Oak HTTP &\nGraphQL Server"]:::core
    click Server "https://github.com/juliendargelos/deno-graphql-api/blob/main/mod.ts"

    %% Core Module Loader and Core Components
    CoreLoader["Core Module Loader"]:::core
    click CoreLoader "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/core/mod.ts"
    ModuleBase["Module Base Class"]:::core
    click ModuleBase "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/core/Module.ts"
    ModelBase["Base Model Class"]:::core
    click ModelBase "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/core/Model.ts"
    CoreResolvers["Core Shared Resolvers"]:::core
    click CoreResolvers "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/core/resolvers.ts"
    CoreTypes["Core GraphQL Types"]:::core
    click CoreTypes "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/core/types.graphql"

    %% Modules Group
    subgraph "Modules" 
        style Modules stroke:#333,stroke-width:2

        %% Article Module
        subgraph "Article Module" 
            ArticleTypes["Article Schema"]:::modules
            click ArticleTypes "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/article/types.graphql"
            ArticleResolvers["Article Resolvers"]:::modules
            click ArticleResolvers "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/article/resolvers.ts"
            ArticleModel["Article Model"]:::modules
            click ArticleModel "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/article/Article.ts"
            ArticleEntry["Article Entrypoint"]:::modules
            click ArticleEntry "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/article/mod.ts"
        end

        %% User Module
        subgraph "User Module"
            UserTypes["User Schema"]:::modules
            click UserTypes "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/user/types.graphql"
            UserResolvers["User Resolvers"]:::modules
            click UserResolvers "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/user/resolvers.ts"
            UserModel["User Model"]:::modules
            click UserModel "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/user/User.ts"
            UserEntry["User Entrypoint"]:::modules
            click UserEntry "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/user/mod.ts"
        end

        %% Authentication Module
        subgraph "Authentication Module"
            AuthTypes["Authentication Schema"]:::modules
            click AuthTypes "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/authentication/types.graphql"
            AuthResolvers["Authentication Resolvers"]:::modules
            click AuthResolvers "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/authentication/resolvers.ts"
            AuthLogic["Authentication Logic"]:::modules
            click AuthLogic "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/authentication/Authentication.ts"
            AuthEntry["Authentication Entrypoint"]:::modules
            click AuthEntry "https://github.com/juliendargelos/deno-graphql-api/blob/main/modules/authentication/mod.ts"
        end
    end

    %% ORM & Migration Engine
    subgraph "cotton ORM & Migrations"
        CottonCLI["cotton CLI"]:::core
        click CottonCLI "https://github.com/juliendargelos/deno-graphql-api/blob/main/bin/cotton.ts"
        ORMConfig["ORM Config"]:::core
        click ORMConfig "https://github.com/juliendargelos/deno-graphql-api/blob/main/ormconfig.ts"
        Migrations["Raw Migrations"]:::core
        click Migrations "https://github.com/juliendargelos/deno-graphql-api/tree/main/migrations/"
    end

    %% Utilities & Config
    subgraph "Environment & Runtime Config"
        EnvLoader["Env Loader"]:::util
        click EnvLoader "https://github.com/juliendargelos/deno-graphql-api/blob/main/environment.ts"
        CacheUtil["Caching Utilities"]:::util
        click CacheUtil "https://github.com/juliendargelos/deno-graphql-api/blob/main/cache.ts"
        ScriptsCfg["Script Hooks Config"]:::util
        click ScriptsCfg "https://github.com/juliendargelos/deno-graphql-api/blob/main/scripts.config.ts"
        ImportMap["Import Map"]:::util
        click ImportMap "https://github.com/juliendargelos/deno-graphql-api/blob/main/importmap.json"
        TSConfig["TS Config"]:::util
        click TSConfig "https://github.com/juliendargelos/deno-graphql-api/blob/main/tsconfig.json"
        Lockfile["Lockfile"]:::util
        click Lockfile "https://github.com/juliendargelos/deno-graphql-api/blob/main/lock.json"
        DockerfileNode["Docker Setup"]:::util
        click DockerfileNode "https://github.com/juliendargelos/deno-graphql-api/tree/main/Dockerfile"
        EnvFile[".env"]:::util
        click EnvFile "https://github.com/juliendargelos/deno-graphql-api/blob/main/.env"
    end

    %% Database
    Database["Relational Database\n(PostgreSQL/SQLite)"]:::external

    %% Dev Tools (Scripts)
    subgraph "Dev Tools"
        Denon["denon (Dev Server)"]:::util
        MigrateCmd["cotton migrate"]:::util
        DockerCmd["docker-compose"]:::util
    end

    %% Relationships
    Client -->|HTTP/GraphQL| Server
    Server -->|loads modules| CoreLoader
    CoreLoader --> CoreResolvers
    CoreLoader --> CoreTypes
    CoreLoader --> ModuleBase
    CoreLoader --> ModelBase

    CoreLoader --> ArticleEntry
    CoreLoader --> UserEntry
    CoreLoader --> AuthEntry

    ArticleEntry --> ArticleTypes
    ArticleEntry --> ArticleResolvers
    ArticleEntry --> ArticleModel

    UserEntry --> UserTypes
    UserEntry --> UserResolvers
    UserEntry --> UserModel

    AuthEntry --> AuthTypes
    AuthEntry --> AuthResolvers
    AuthEntry --> AuthLogic

    ArticleResolvers -->|uses| ArticleModel
    UserResolvers -->|uses| UserModel
    AuthResolvers -->|uses| AuthLogic

    ArticleModel -->|CRUD via cotton| ModelBase
    UserModel -->|CRUD via cotton| ModelBase
    AuthLogic -->|DB access| ModelBase

    ModelBase -->|SQL| Database
    CottonCLI -->|runs migrations| Migrations
    Migrations -->|applies to| Database
    ORMConfig -->|configures| ModelBase

    Server -->|context injection| AuthLogic

    Server -->|env & util| EnvLoader
    Server --> CacheUtil
    Server --> ScriptsCfg
    Server --> ImportMap
    Server --> TSConfig
    Server --> Lockfile
    Server --> DockerfileNode
    Server --> EnvFile

    Denon --> Server
    MigrateCmd --> CottonCLI
    DockerCmd --> Server
    DockerCmd --> Database

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef modules fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px
```
