# cryptomafiapb/inkwell architecture

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

- Interactive diagram: https://gitdiagram.com/cryptomafiapb/inkwell
- Repository: https://github.com/cryptomafiapb/inkwell

## Overview

##### Project Type & Purpose
- This is a backend-only REST API (no SPA/SSR frontend) built with Node.js, Express.js and MongoDB.
- Purpose: Provide a modular, production-ready blog publishing API with JWT+API-Key authentication, role-based access, admin approval workflow, rate-limiting, and robust error handling.

##### File Structure Analysis & Architectural Patterns
- src/index.js & src/app.js: Bootstrapping & Express application setup.
- src/routes: Defines HTTP routes, groups endpoints by domain (auth, posts, admin, etc).
- src/controllers: Implements request handlers (controller layer in MVC).
- src/models: Mongoose schemas mapping to MongoDB collections (data layer).
- src/db/dbConnect.js: MongoDB connection logic.
- src/middlewares: Cross-cutting concerns (authentication, rate limiting, error handling).
- src/validators: Joi or similar schemas for request payload validation (input layer).
- src/utils: Shared helpers (error classes, response formatting, constants).

Architectural pattern: Classic layered MVC (or “router → controller → model”) with middleware “pipeline” for cross-cutting concerns.

##### Key README Insights
- Tech stack: Express.js, MongoDB/Mongoose, JWT, API-Key security, rate-limiter.
- Features: Authentication, role-based access, category & comment CRUD, admin approval workflow, audit logging in post_reviews.
- External services: None beyond MongoDB. Testing via Postman collection.

##### Components
a. Main Components
- Clients (Postman, browser, mobile app)
- API Gateway (Express.js entry point)
- Middleware Layer
- Routing Layer
- Controller Layer
- Data Access Layer (Mongoose models + dbConnect)
- MongoDB Database
- External Config (Environment variables)
b. Relationships & Interactions
1. Client → HTTP(S) request → Express.js server (src/index.js/app.js)
2. Request flows through global middlewares (rateLimit, auth, validation)
3. Routed to specific Router (e.g., auth.route.js)
4. Router invokes corresponding Controller (e.g., auth.controller.js)
5. Controller uses Models (e.g., users.model.js, posts.model.js) via dbConnect
6. MongoDB executes queries/transactions
7. Controller returns data or error → Response formatted via utils/api-response
8. Error flows back through error.middleware if thrown
c. Architectural Patterns & Principles
- Layered separation (Middleware → Router → Controller → Model → DB)
- Single Responsibility: each middleware, controller, model has one focus
- Dependency Injection by requiring modules, centralized config
- Modular folder structure for maintainability and scalability
d. Key Technologies & Libraries
- Node.js & Express.js (HTTP server & routing)
- Mongoose (ODM for MongoDB)
- JWT & API-Key mechanisms in auth.middleware
- express-rate-limit for rateLimit.middleware
- Joi or similar for request validators

##### Detailed Elements to Capture
- Entry point (src/index.js) reading env vars, connecting to DB, starting server
- app.js setup: global middlewares (rateLimit, auth, error) + mounting routers
- Separate route modules for each feature domain
- Controller actions invoking model operations, logging to post_reviews on approve/reject
- Model definitions for each collection (users, posts, comments, categories, api_keys, post_reviews)
- Error middleware catching and formatting errors via utils/api-error

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    subgraph "External Layer"
        Clients["Clients (Postman, Browser, Mobile)"]:::external
        EnvConfig["Environment Config"]:::external
    end

    %% API Server Layer
    subgraph "API Server (Node.js/Express)" 
        subgraph "API Gateway"
            Index["src/index.js"]:::api
            App["src/app.js"]:::api
        end
        subgraph "Middleware Layer"
            RateLimit["Rate Limiting Middleware"]:::api
            AuthM["Auth & Authorization Middleware"]:::api
            ErrorM["Global Error Handling Middleware"]:::api
        end
        subgraph "Validation Layer"
            AuthV["Auth Request Validation"]:::api
            PostV["Post Request Validation"]:::api
            CatV["Category Request Validation"]:::api
            CommV["Comment Request Validation"]:::api
        end
        subgraph "Routing Layer"
            AuthR["Authentication Routes"]:::api
            PostsR["Posts Routes"]:::api
            AdminR["Admin Routes"]:::api
        end
        subgraph "Controller Layer"
            AuthC["Authentication Controller"]:::api
            PostsC["Posts Controller"]:::api
            AdminC["Admin Controller"]:::api
            CatC["Categories Controller"]:::api
            CommC["Comments Controller"]:::api
            HealthC["Health Check Controller"]:::api
        end
        subgraph "Utility Modules"
            ErrU["API Error Class & Formatter"]:::api
            ResU["Standard API Response Formatter"]:::api
            ConstU["Application-wide Constants"]:::api
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        DBConn["src/db/dbConnect.js"]:::data
        UsersM["src/models/users.model.js"]:::data
        PostsM["src/models/posts.model.js"]:::data
        CatsM["src/models/categories.model.js"]:::data
        CommsM["src/models/comments.model.js"]:::data
        APIKeysM["src/models/api_keys.model.js"]:::data
        ReviewsM["src/models/post_reviews.model.js"]:::data
    end

    %% Database
    subgraph "Database"
        MongoDB["MongoDB"]:::db
    end

    %% Connections
    Clients -->|"HTTP Request"| Index
    EnvConfig -.-> Index
    Index --> App
    Index --> DBConn
    DBConn --> MongoDB

    App --> RateLimit
    RateLimit --> AuthM
    AuthM --> AuthV
    AuthM --> PostV
    AuthM --> CatV
    AuthM --> CommV

    AuthV --> AuthR
    PostV --> PostsR
    CatV --> AuthR
    CommV --> PostsR

    AuthR --> AuthC
    PostsR --> PostsC
    AdminR --> AdminC

    App --> HealthC

    AuthC --> UsersM
    AuthC --> APIKeysM
    PostsC --> PostsM
    AdminC --> ReviewsM
    CatC --> CatsM
    CommC --> CommsM

    AuthC --> ErrU
    PostsC --> ErrU
    AdminC --> ErrU
    CatC --> ErrU
    CommC --> ErrU
    HealthC --> ErrU

    AuthC --> ResU
    PostsC --> ResU
    AdminC --> ResU
    CatC --> ResU
    CommC --> ResU
    HealthC --> ResU

    UsersM --> MongoDB
    PostsM --> MongoDB
    CatsM --> MongoDB
    CommsM --> MongoDB
    APIKeysM --> MongoDB
    ReviewsM --> MongoDB

    %% Click Events
    click Index "https://github.com/cryptomafiapb/inkwell/blob/main/src/index.js"
    click App "https://github.com/cryptomafiapb/inkwell/blob/main/src/app.js"
    click EnvConfig "https://github.com/cryptomafiapb/inkwell/blob/main/package.json"
    click EnvConfig "https://github.com/cryptomafiapb/inkwell/blob/main/README.md"
    click EnvConfig "https://github.com/cryptomafiapb/inkwell/blob/main/eslint.config.js"
    click DBConn "https://github.com/cryptomafiapb/inkwell/blob/main/src/db/dbConnect.js"
    click RateLimit "https://github.com/cryptomafiapb/inkwell/blob/main/src/middlewares/rateLimit.middleware.js"
    click AuthM "https://github.com/cryptomafiapb/inkwell/blob/main/src/middlewares/auth.middleware.js"
    click ErrorM "https://github.com/cryptomafiapb/inkwell/blob/main/src/middlewares/error.middleware.js"
    click AuthR "https://github.com/cryptomafiapb/inkwell/blob/main/src/routes/auth.route.js"
    click PostsR "https://github.com/cryptomafiapb/inkwell/blob/main/src/routes/posts.route.js"
    click AdminR "https://github.com/cryptomafiapb/inkwell/blob/main/src/routes/admin.route.js"
    click AuthC "https://github.com/cryptomafiapb/inkwell/blob/main/src/controllers/auth.controller.js"
    click PostsC "https://github.com/cryptomafiapb/inkwell/blob/main/src/controllers/posts.controller.js"
    click AdminC "https://github.com/cryptomafiapb/inkwell/blob/main/src/controllers/admin.controller.js"
    click CatC "https://github.com/cryptomafiapb/inkwell/blob/main/src/controllers/category.controller.js"
    click CommC "https://github.com/cryptomafiapb/inkwell/blob/main/src/controllers/comments.controller.js"
    click HealthC "https://github.com/cryptomafiapb/inkwell/blob/main/src/controllers/healthCheck.controller.js"
    click AuthV "https://github.com/cryptomafiapb/inkwell/blob/main/src/validators/authSchema.js"
    click PostV "https://github.com/cryptomafiapb/inkwell/blob/main/src/validators/postSchema.js"
    click CatV "https://github.com/cryptomafiapb/inkwell/blob/main/src/validators/categorySchema.js"
    click CommV "https://github.com/cryptomafiapb/inkwell/blob/main/src/validators/commentSchema.js"
    click UsersM "https://github.com/cryptomafiapb/inkwell/blob/main/src/models/users.model.js"
    click PostsM "https://github.com/cryptomafiapb/inkwell/blob/main/src/models/posts.model.js"
    click CatsM "https://github.com/cryptomafiapb/inkwell/blob/main/src/models/categories.model.js"
    click CommsM "https://github.com/cryptomafiapb/inkwell/blob/main/src/models/comments.model.js"
    click APIKeysM "https://github.com/cryptomafiapb/inkwell/blob/main/src/models/api_keys.model.js"
    click ReviewsM "https://github.com/cryptomafiapb/inkwell/blob/main/src/models/post_reviews.model.js"
    click ErrU "https://github.com/cryptomafiapb/inkwell/blob/main/src/utils/api-error.js"
    click ResU "https://github.com/cryptomafiapb/inkwell/blob/main/src/utils/api-responce.js"
    click ConstU "https://github.com/cryptomafiapb/inkwell/blob/main/src/utils/constants.js"

    %% Styles
    classDef external fill:#e0f7e9,stroke:#333,stroke-width:1px
    classDef api fill:#d0e8ff,stroke:#333,stroke-width:1px
    classDef data fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef db fill:#fff5be,stroke:#333,stroke-width:1px
```
