# fims-proto/fims-proto-ms architecture

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

- Interactive diagram: https://gitdiagram.com/fims-proto/fims-proto-ms
- Repository: https://github.com/fims-proto/fims-proto-ms

## Overview

##### Main Components Identification
- External Clients: Represent the fims-proto-ui (frontend) and any other consumers (like Postman or scripted clients) interacting with the system.
- API Gateway: Denoted by ORY Oathkeeper (listening on port 4455). This component handles access control, routing traffic from the frontend/API requests to the backend.
- Backend Microservice: fims-proto-ms, which is the core backend service running on port 5002. It includes your entry point (cmd/main.go) and multiple domain-specific modules.
- Supporting Infrastructure: Infrastructure components such as Postgres (and other services from the fims-dev-environment), Docker orchestration, and configuration management (files under config/).

##### Internal Architectural Layers & Modules
- Entry Point and API Layer:
– “cmd/main.go” is the service entry point.
– “api/” and the subdirectories under “internal” (each having public and private HTTP ports) comprise the API layer. This should be represented as the front-facing endpoints where HTTP requests are processed.
- Domain Specific Modules:
– General Ledger Module: Found in internal/general_ledger. Break it into its sub-layers: domain (business rules), application (commands and queries), adapters (DB, numbering, SOB, user, etc.), and ports (both public HTTP and intraprocess communication).
– Numbering Module: Located in internal/numbering, with similar sub-layer separation.
– SOB Module: In internal/sob, again with its layered structure.
– User Module: In internal/user, maintaining its own domain, application, and port components.
- Common/Core Services:
– “internal/common/” holds libraries for configuration, data management (filterable, pageable, sortable, schema), datasource connectivity, logging, error handling, and localization.
– These should be illustrated as foundational components that provide cross-cutting services to each domain module.
- DevOps & Build Infrastructure:
– Dockerfile, .dockerignore, Makefile, and GitHub workflows indicate automated builds and deployment integrations. Represent these as assembly/build/deployment layers outside the runtime logic.

- External Clients (frontend, Postman) sending HTTP requests to the API Gateway (ORY Oathkeeper on port 4455).
- The gateway forwards the requests to the fims-proto-ms backend service (port 5002) where the API layer dispatches them based on the specific domain (General Ledger, Numbering, SOB, User).
- Within each domain module, illustrate the flow:
– The API/HTTP layer routes commands (create, update, query, etc.) to the Application Layer.
– The Application Layer interacts with the Domain (business logic) and then uses Adapters (e.g., DB repositories, intraprocess calls) to persist or retrieve data.
- That common libraries (logging, configuration, etc.) supplement the domain modules.
- Optionally, include a representation of the Postgres database and any other external services (like ORY Kratos for user management) as external components the backend interacts with.
– Also show responses flowing back along these paths.

##### Architectural Patterns & Technologies
- That the project follows a modular, layered (clean/hexagonal architecture) approach with distinct separation of concerns.
- Components that relate to dependency injection (e.g., configuration via “internal/common/config”) and cross-cutting concerns (e.g., logging and error handling).
- Mention the integration with containerized infra via Docker and CI/CD via GitHub actions.

##### Specific Elements
- Clearly separate layers:
– External Interface Layer (Clients/Frontend, API Gateway)
– Service/Application Layer (fims-proto-ms including the cmd/main.go and API layer)
– Domain Modules Layer (General Ledger, Numbering, SOB, User, etc.)
– Common Libraries/Services Layer (configuration, logging, error handling, etc.)
– Infrastructure Layer (Database, Docker, CI/CD pipelines)
- Optionally insert callouts for special scripts (like the user creation/invitation flow from the README) to indicate how user management integrates into the overall system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Title
    Title["fims-proto-ms System Architecture"]:::title

    %% External Interface Layer
    subgraph "External Interface"
        ext_clients["External Clients<br/>(fims-proto-ui, Postman)"]:::external
        api_gateway["API Gateway<br/>(ORY Oathkeeper:4455)"]:::external
    end

    %% Backend Service Layer
    subgraph "Backend Service"
        fims_backend["fims-proto-ms Backend<br/>(Port: 5002)"]:::backend
        entrypoint["Entry Point<br/>(cmd/main.go)"]:::backend
        api_layer["API Layer<br/>(api/api.go)"]:::backend
    end

    %% Domain Modules Layer
    subgraph "Domain Modules"
        gl_module["General Ledger Module<br/>(internal/general_ledger)"]:::module
        num_module["Numbering Module<br/>(internal/numbering)"]:::module
        sob_module["SOB Module<br/>(internal/sob)"]:::module
        user_module["User Module<br/>(internal/user)"]:::module
    end

    %% Common/Core Services Layer
    subgraph "Common Services"
        common_services["Common/Core Services<br/>(internal/common)"]:::common
        config_mgmt["Configuration Management<br/>(config)"]:::common
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        postgres["Postgres Database"]:::database
        devops["DevOps & Build Infrastructure"]:::infrachain
        docker["Dockerfile"]:::infra
        dockerignore[".dockerignore"]:::infra
        makefile["Makefile"]:::infra
        github[".github/workflows"]:::infra
    end

    %% Connections: External Interface to Backend
    ext_clients -->|"HTTP_Request"| api_gateway
    api_gateway -->|"Routes_to"| api_layer

    %% Connections: Within Backend Service
    entrypoint -->|"Initializes"| api_layer

    %% Connections: API Layer to Domain Modules
    api_layer -->|"Dispatches"| gl_module
    api_layer -->|"Dispatches"| num_module
    api_layer -->|"Dispatches"| sob_module
    api_layer -->|"Dispatches"| user_module

    %% Connections: Domain Modules interacting with Common Services
    api_layer -->|"Utilizes"| common_services
    gl_module -->|"Uses"| common_services
    num_module -->|"Uses"| common_services
    sob_module -->|"Uses"| common_services
    user_module -->|"Uses"| common_services
    common_services -->|"Reads"| config_mgmt

    %% Connections: Domain Modules performing DB operations
    gl_module -->|"DB_calls"| postgres
    num_module -->|"DB_calls"| postgres
    sob_module -->|"DB_calls"| postgres
    user_module -->|"DB_calls"| postgres

    %% Connections: Deployment & Build Infrastructure
    fims_backend -->|"Deployed_via"| devops
    devops --> docker
    devops --> dockerignore
    devops --> makefile
    devops --> github

    %% Click Events
    click entrypoint "https://github.com/fims-proto/fims-proto-ms/blob/master/cmd/main.go"
    click api_layer "https://github.com/fims-proto/fims-proto-ms/blob/master/api/api.go"
    click gl_module "https://github.com/fims-proto/fims-proto-ms/tree/master/internal/general_ledger"
    click num_module "https://github.com/fims-proto/fims-proto-ms/tree/master/internal/numbering"
    click sob_module "https://github.com/fims-proto/fims-proto-ms/tree/master/internal/sob"
    click user_module "https://github.com/fims-proto/fims-proto-ms/tree/master/internal/user"
    click common_services "https://github.com/fims-proto/fims-proto-ms/tree/master/internal/common"
    click config_mgmt "https://github.com/fims-proto/fims-proto-ms/tree/master/config"
    click docker "https://github.com/fims-proto/fims-proto-ms/tree/master/Dockerfile"
    click dockerignore "https://github.com/fims-proto/fims-proto-ms/blob/master/.dockerignore"
    click makefile "https://github.com/fims-proto/fims-proto-ms/tree/master/Makefile"
    click github "https://github.com/fims-proto/fims-proto-ms/tree/master/.github/workflows"

    %% Styles
    classDef title fill:#ffffff,stroke:#000000,stroke-width:2px;
    classDef external fill:#cce5ff,stroke:#2b7cff,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef module fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef common fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef database fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef infra fill:#d1c4e9,stroke:#8e44ad,stroke-width:2px;
    classDef infrachain fill:#d1c4e9,stroke:#8e44ad,stroke-width:2px;
```
