# ashermorse/locksmith architecture

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

- Interactive diagram: https://gitdiagram.com/ashermorse/locksmith
- Repository: https://github.com/ashermorse/locksmith

## Overview

##### Overall Project Perspective
- That it is a backend service built with Express.js and TypeScript, designed primarily for authentication and user profile management.

##### Main Components
a. Server and API Layer:

b. Feature Modules:
- A controller (e.g., src/features/auth/controller.ts and src/features/profile/controller.ts) that manages HTTP requests.
- Service layer (src/features/auth/service.ts and src/features/profile/service.ts) that contains the business logic.
- Use a repository component (src/features/auth/repository.ts and src/features/profile/repository.ts) to handle interactions with the database.
- Validators (e.g., validator.ts files) to indicate request data validation using Zod.
- Optionally, add a “types” module for type definitions that help in maintaining type safety.

c. Shared Infrastructure:
- Middleware (auth, error handling, file uploading) from src/shared/middleware.
- Utilities and constants (from src/shared/constants.ts and src/shared/utils.ts) that are used across multiple modules.
- Shared types that enforce uniform API responses and Express augmentations.

d. Database Layer:
- PostgreSQL as an external database element.
- Optionally, show the “uploads” folder which holds profile images, indicating file system storage (or potential to swap in cloud storage).

e. Authentication & Security:
- JWT configuration (using src/config/jwt.ts) showing how JWT tokens (access and refresh tokens) are generated and validated.
- Use of Passport.js for authentication, and Bcrypt for password hashing, if mentioned in your tech stack.

f. API Documentation:
- A component that represents Swagger (from src/swagger components) which visually depicts the API documentation available at the /docs route.

##### Relationships and Data Flow
- From the server, indicate that requests are routed to either “Auth” or “Profile” feature modules.
- Within each feature module, show the flow from Routes → Controller → Service → Repository → Database.
- Middleware (authentication, error handling, upload) as intercepting layers before the controller logic.
- Swagger component back to the API endpoints, indicating documentation and testing.

##### Architectural Design Principles
- Point out the modular, feature-based architecture which makes the application easily extensible.
- Separation of concerns (controllers for handling requests, services for business logic, repositories for data access).
- How middleware abstracts cross-cutting concerns such as authentication and error management.
- Mention the use of environment variables (.env) for configuration, reinforcing secure and flexible deployments.

##### Technology Stack Labels
- Components with the technologies used. For example:
- “Express.js & TypeScript – API Server”
- “Drizzle ORM & PostgreSQL – Data Persistence”
- “JWT & Passport.js – Authentication”
- “Swagger – API Documentation”
- “Zod – Validation”
- “Multer – File Uploads”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client("Client"):::client
    ExpressServer("Express.js Server<br/>(Express.js & TypeScript)"):::server

    %% Shared Infrastructure
    subgraph "Shared Infrastructure"
        SharedMiddleware("Shared Middleware<br/>(Auth, Error Handling,<br/>File Upload)"):::middleware
        Constants("Constants"):::util
        Utils("Utils"):::util
        JWTConfig("JWT Configuration<br/>(JWT & Passport.js)"):::config
    end

    %% API Documentation
    APIDocs("API Documentation<br/>(Swagger)"):::docs

    %% Database and Storage
    DrizzleORM("Drizzle ORM Integration<br/>(PostgreSQL)"):::db
    UploadStorage("Uploads Storage<br/>(Profile Images)"):::storage

    %% Authentication Module
    subgraph "Authentication Module"
        AuthRoutes("Auth Routes"):::route
        AuthValidator("Auth Validators<br/>(Zod)"):::validator
        AuthController("Auth Controller"):::controller
        AuthService("Auth Service"):::service
        AuthRepo("Auth Repository"):::repository
    end

    %% Profile Module
    subgraph "Profile Module"
        ProfileRoutes("Profile Routes"):::route
        ProfileValidator("Profile Validators<br/>(Zod)"):::validator
        ProfileController("Profile Controller"):::controller
        ProfileService("Profile Service"):::service
        ProfileRepo("Profile Repository"):::repository
    end

    %% Data Flow
    Client -->|"HTTP Request"| ExpressServer
    ExpressServer -->|"API docs at /docs"| APIDocs
    ExpressServer -->|"Routes"| AuthRoutes
    ExpressServer -->|"Routes"| ProfileRoutes

    %% Shared Middleware integration for both modules
    AuthRoutes -->|"passes through"| SharedMiddleware
    ProfileRoutes -->|"passes through"| SharedMiddleware

    SharedMiddleware -->|"validates"| AuthValidator
    SharedMiddleware -->|"validates"| ProfileValidator

    AuthValidator --> AuthController
    AuthController --> AuthService
    AuthService --> AuthRepo
    AuthRepo -->|"DB operations"| DrizzleORM

    ProfileValidator --> ProfileController
    ProfileController --> ProfileService
    ProfileService --> ProfileRepo
    ProfileRepo -->|"DB operations"| DrizzleORM

    %% Additional connections
    JWTConfig ---|"configures"| AuthService
    ProfileService ---|"handles file uploads"| UploadStorage
    ExpressServer ---|"uses"| Constants
    ExpressServer ---|"uses"| Utils

    %% Click Events
    click ExpressServer "https://github.com/ashermorse/locksmith/blob/main/server.ts"
    click AuthRoutes "https://github.com/ashermorse/locksmith/blob/main/src/features/auth/routes.ts"
    click ProfileRoutes "https://github.com/ashermorse/locksmith/blob/main/src/features/profile/routes.ts"
    click AuthController "https://github.com/ashermorse/locksmith/blob/main/src/features/auth/controller.ts"
    click ProfileController "https://github.com/ashermorse/locksmith/blob/main/src/features/profile/controller.ts"
    click AuthService "https://github.com/ashermorse/locksmith/blob/main/src/features/auth/service.ts"
    click ProfileService "https://github.com/ashermorse/locksmith/blob/main/src/features/profile/service.ts"
    click AuthRepo "https://github.com/ashermorse/locksmith/blob/main/src/features/auth/repository.ts"
    click ProfileRepo "https://github.com/ashermorse/locksmith/blob/main/src/features/profile/repository.ts"
    click AuthValidator "https://github.com/ashermorse/locksmith/blob/main/src/features/auth/validator.ts"
    click ProfileValidator "https://github.com/ashermorse/locksmith/blob/main/src/features/profile/validator.ts"
    click SharedMiddleware "https://github.com/ashermorse/locksmith/tree/main/src/shared/middleware"
    click Constants "https://github.com/ashermorse/locksmith/blob/main/src/shared/constants.ts"
    click Utils "https://github.com/ashermorse/locksmith/blob/main/src/shared/utils.ts"
    click DrizzleORM "https://github.com/ashermorse/locksmith/tree/main/src/db"
    click JWTConfig "https://github.com/ashermorse/locksmith/blob/main/src/config/jwt.ts"
    click APIDocs "https://github.com/ashermorse/locksmith/tree/main/src/swagger"
    click UploadStorage "https://github.com/ashermorse/locksmith/tree/main/uploads/profiles"

    %% Styles
    classDef client fill:#ffefef,stroke:#d33,stroke-width:2px;
    classDef server fill:#e0f7fa,stroke:#00796b,stroke-width:2px;
    classDef middleware fill:#fff3e0,stroke:#fb8c00,stroke-width:2px;
    classDef route fill:#e8f5e9,stroke:#43a047,stroke-width:2px;
    classDef validator fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
    classDef controller fill:#ede7f6,stroke:#5e35b1,stroke-width:2px;
    classDef service fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px;
    classDef repository fill:#fbe9e7,stroke:#d84315,stroke-width:2px;
    classDef db fill:#fffde7,stroke:#f9a825,stroke-width:2px,stroke-dasharray: 5,5;
    classDef config fill:#e0f2f1,stroke:#00796b,stroke-width:2px;
    classDef docs fill:#f1f8e9,stroke:#7cb342,stroke-width:2px;
    classDef storage fill:#fce4ec,stroke:#c2185b,stroke-width:2px;
    classDef util fill:#eceff1,stroke:#546e7a,stroke-width:2px;
```
