# ssaavedraa/mjolnircore architecture

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

- Interactive diagram: https://gitdiagram.com/ssaavedraa/mjolnircore
- Repository: https://github.com/ssaavedraa/mjolnircore

## Overview

##### Project type and purpose
- Project name: MjolnirCore
- Type: Backend monolithic API service (no separate frontend)
- Purpose: Core framework for a CMS, exposes REST endpoints to manage Users, Companies, Products, Teams, and handles authentication, email invites, and data persistence.

##### High-level architectural pattern
- Layered (also maps to a hexagonal/clean architecture):
- Presentation/API layer (Gin router → Controllers)
- Application/Business layer (Services → Business rules)
- Data layer (Repositories → Database)
- Infrastructure/Adapters (Config, Utils, Interfaces to external services)

##### Main components
A. External Clients & Entry Points
- Client apps or CURL → HTTP requests to API
- Docker / Docker-Compose container for local dev

B. API Layer
- Gin HTTP Server (cmd/main.go)
- Router definitions (pkg/routes/routes.go)

C. Controllers (pkg/controllers)
- UserController, CompanyController, ProductController, TeamController
- Accept HTTP requests → orchestrate service calls

D. Services (pkg/services)
- Business logic per domain (e.g., user invite, product creation)
- Call into repositories, utils (e.g., JWT, bcrypt wrappers)

E. Repositories (pkg/repositories)
- Data access layer (CRUD operations)
- Uses config/db migration + database driver to persist models

F. Models & DTOs
- Domain models (pkg/models)
- Data Transfer Objects (pkg/dtos) for API contracts

G. Configuration & Infrastructure
- Config loader (pkg/config) reading .env, air.toml, docker-compose.yml
- Database migrations (pkg/config/db/migrations)
- Utility wrappers: bcrypt, JWT, ID Generator, Email sender (pkg/utils & pkg/interfaces)
- i18n static JSON files + Invite email HTML template

H. External Services
- SMTP Email provider
- (Optional future) Kafka producer interface

I. Database
- PostgreSQL or MySQL (configured via .env, managed via docker-compose)

##### Relationships & data flows
1. Client → HTTP request → Gin Router
2. Router → Controller → Service
3. Service → Repository → Database
4. Service → Utility/Interface adapters (e.g., JWT, bcrypt, email sender)
5. Response flows back in reverse: DB → Repo → Service → Controller → JSON → Client

##### Architectural patterns & design principles
- Single Responsibility per layer
- Dependency Injection via interface definitions (pkg/interfaces) + mockery for testing
- Separation of concerns: controllers do no DB work; repos know nothing about HTTP
- Config and environment isolation
- Hexagonal style: core logic in services, ports & adapters at edges

##### Detail to capture
- All top-level packages and their responsibilities
- Interface boundaries and how dependencies are injected
- Build & deployment artifacts (Dockerfile, docker-compose.yml)
- DB migration versioning (SQL scripts)
- Test harness: mocks directory indicates decoupled design

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients & Entry Points
    subgraph "Clients & Entry Points"
        direction TB
        Client["External Client / CURL"]:::external
        DockerfileNode["Dockerfile"]:::external
        DockerCompose["docker-compose.yml"]:::external
        EnvFile[".env.example"]:::external
    end

    %% API Layer & Routing
    subgraph "API Layer"
        direction TB
        MainApp["Gin HTTP Server"]:::api
        Router["Router Definitions"]:::api
    end

    %% Controllers
    subgraph "Controllers"
        direction TB
        UserCtrl["UserController"]:::api
        CompanyCtrl["CompanyController"]:::api
        ProductCtrl["ProductController"]:::api
        TeamCtrl["TeamController"]:::api
    end

    %% Services
    subgraph "Services"
        direction TB
        UserSvc["UserService"]:::service
        CompanySvc["CompanyService"]:::service
        ProductSvc["ProductService"]:::service
        TeamSvc["TeamService"]:::service
    end

    %% Repositories & Database
    subgraph "Repositories & Database"
        direction TB
        UserRepo["UserRepository"]:::repo
        CompanyRepo["CompanyRepository"]:::repo
        ProductRepo["ProductRepository"]:::repo
        TeamRepo["TeamRepository"]:::repo
        RoleRepo["RoleRepository"]:::repo
        Database["Database (PostgreSQL/MySQL)"]:::repo
    end

    %% Infrastructure & Utilities
    subgraph "Infrastructure & Utilities"
        direction TB
        Config["Config Loader"]:::infra
        Migrations["DB Migrations"]:::infra
        Bcrypt["Bcrypt Wrapper"]:::infra
        JWT["JWT Wrapper"]:::infra
        EmailSender["Email Sender"]:::infra
        IDGen["ID Generator"]:::infra
        Logging["Logging"]:::infra
        I18n["i18n JSON Files"]:::infra
        Template["Email Template"]:::infra
        SMTP["SMTP Email Provider"]:::external
    end

    %% Flows
    Client -->|HTTP Request| MainApp
    MainApp -->|uses| Router
    Router -->|routes to| UserCtrl
    Router -->|routes to| CompanyCtrl
    Router -->|routes to| ProductCtrl
    Router -->|routes to| TeamCtrl

    UserCtrl -->|calls| UserSvc
    CompanyCtrl -->|calls| CompanySvc
    ProductCtrl -->|calls| ProductSvc
    TeamCtrl -->|calls| TeamSvc

    UserSvc -->|CRUD| UserRepo
    CompanySvc -->|CRUD| CompanyRepo
    ProductSvc -->|CRUD| ProductRepo
    TeamSvc -->|CRUD| TeamRepo

    UserSvc -->|uses| Bcrypt
    UserSvc -->|uses| JWT
    UserSvc -->|uses| EmailSender
    UserSvc -->|uses| IDGen

    Config -->|provides| MainApp
    Migrations -->|runs against| Database
    Database -->|persist data| UserRepo
    Database -->|persist data| CompanyRepo
    Database -->|persist data| ProductRepo
    Database -->|persist data| TeamRepo
    Database -->|persist data| RoleRepo

    EmailSender -->|sends via| SMTP
    I18n -->|used by| EmailSender
    Template -->|used by| EmailSender
    Logging -->|used by| MainApp

    %% Click Events
    click DockerfileNode "https://github.com/ssaavedraa/mjolnircore/tree/main/Dockerfile"
    click DockerCompose "https://github.com/ssaavedraa/mjolnircore/blob/main/docker-compose.yml"
    click EnvFile "https://github.com/ssaavedraa/mjolnircore/blob/main/.env.example"
    click MainApp "https://github.com/ssaavedraa/mjolnircore/blob/main/cmd/main.go"
    click Router "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/routes/routes.go"
    click UserCtrl "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/controllers/user_controller.go"
    click UserCtrl "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/controllers/user_controller_impl.go"
    click CompanyCtrl "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/controllers/company_controller.go"
    click CompanyCtrl "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/controllers/company_controller_impl.go"
    click ProductCtrl "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/controllers/product_controller.go"
    click ProductCtrl "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/controllers/product_controller_impl.go"
    click TeamCtrl "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/controllers/team_controller.go"
    click TeamCtrl "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/controllers/team_controller_impl.go"
    click UserSvc "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/services/user_service.go"
    click UserSvc "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/services/user_service_impl.go"
    click CompanySvc "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/services/company_service.go"
    click CompanySvc "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/services/company_service_impl.go"
    click ProductSvc "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/services/product_service.go"
    click ProductSvc "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/services/product_service_impl.go"
    click TeamSvc "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/services/team_service.go"
    click TeamSvc "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/services/team_service_impl.go"
    click UserRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/user_repository.go"
    click UserRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/user_repository_impl.go"
    click CompanyRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/company_repository.go"
    click CompanyRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/company_repository_impl.go"
    click ProductRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/product_repository.go"
    click ProductRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/product_repository_impl.go"
    click TeamRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/team_repository.go"
    click TeamRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/team_repository_impl.go"
    click RoleRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/role_repository.go"
    click RoleRepo "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/repositories/role_repository_impl.go"
    click Config "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/config/config.go"
    click Config "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/config/config_impl.go"
    click Migrations "https://github.com/ssaavedraa/mjolnircore/tree/main/pkg/config/db/migrations"
    click Bcrypt "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/utils/wrappers/bcrypt_wrapper.go"
    click JWT "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/utils/wrappers/jwt_wrapper.go"
    click EmailSender "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/utils/email_sender.go"
    click IDGen "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/utils/id_generator.go"
    click Logging "https://github.com/ssaavedraa/mjolnircore/blob/main/pkg/utils/logging/logging.go"
    click I18n "https://github.com/ssaavedraa/mjolnircore/blob/main/i18n/user_invite_mvp/en.json"
    click I18n "https://github.com/ssaavedraa/mjolnircore/blob/main/i18n/user_invite_mvp/es.json"
    click Template "https://github.com/ssaavedraa/mjolnircore/blob/main/templates/user_invite_mvp/index.html"

    %% Styles
    classDef api fill:#D0E6FF,stroke:#003399,color:#003399
    classDef service fill:#DFF5D0,stroke:#339900,color:#339900
    classDef repo fill:#FFE7C4,stroke:#CC6600,color:#CC6600
    classDef infra fill:#E0E0E0,stroke:#666666,color:#333333
    classDef external fill:#F2F2F2,stroke:#999999,color:#666666
```
