How fims-proto/fims-proto-ms works
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.