# fusion-hr-solution/fusion architecture

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

- Interactive diagram: https://gitdiagram.com/fusion-hr-solution/fusion
- Repository: https://github.com/fusion-hr-solution/fusion

## Overview

1. This repository is split into two major monorepos: a .NET backend under `Backend/` and a Next.js/Turborepo frontend under `Frontend/`. The backend is service-oriented; the frontend is microfrontend-oriented.

2. The backend has four clear boundaries:
   - `EY.HRPlatform.Gateway` as the single HTTP entry point
   - `EY.HRPlatform.Identity` for authentication and user management
   - `EY.HRPlatform.Training` for course/training APIs
   - `EY.HRPlatform.SharedKernel` for shared domain and CQRS primitives

3. The gateway is an ASP.NET reverse proxy layer built with YARP. Its purpose is to sit in front of the services, enforce JWT validation on protected routes, add correlation IDs for request tracing, and handle cross-origin access from the frontend. In the architecture diagram, it is the main north-south traffic choke point.

4. The Identity service is the most fully implemented backend service. It contains controllers for auth and users, ASP.NET Identity-style persistence with EF Core, token issuance/rotation, a seeder, and migrations. Its domain model includes `ApplicationUser`, `RefreshToken`, and role concepts (`Admin`, `HR`, `Employee`, `Manager`), so it is both the auth provider and the user/RBAC source of truth.

5. The Training service is a separate Web API with a `CoursesController`, but from the repository contents it appears mostly scaffolded/stubbed compared with Identity. It still represents an independent bounded context behind the gateway and is intended to own learning/course data.

6. `SharedKernel` is the backend’s reusable foundation layer. It defines CQRS interfaces (`ICommand`, `IQuery`, handlers), base domain types (`BaseEntity`, `AggregateRoot`, domain events), a strongly typed value object (`EmployeeId`), a result/error pattern, and integration event contracts such as `EmployeeCreatedIntegrationEvent`. This indicates the backend is designed for domain-driven boundaries even though only some services are implemented.

7. The backend data flow is: frontend calls the gateway, the gateway routes the request to Identity or Training, and Identity persists to PostgreSQL via EF Core. Authentication flows go through login/register/refresh endpoints in Identity, with JWTs returned to the client and refresh tokens stored server-side. The presence of integration event types suggests future async/event-driven integration, but no broker is visible in the current tree.

8. The frontend is a microfrontend workspace managed by pnpm and Turborepo. It contains a `shell` app plus six domain apps: `core`, `interview`, `learning`, `performance`, `recruitment`, and `onboarding`. Each app is a separate Next.js application with its own page/layout/error/loading boundaries, while `Frontend/packages/ui` provides shared UI primitives used across apps.

9. The `shell` app is the host/entry point for the frontend experience. Per the README, it serves unified routing and proxies the individual MFEs under path prefixes such as `/learning`, `/recruitment`, and `/onboarding`. That makes `shell` the browser-facing composition layer, while each MFE owns its own domain screen and client-side service module.

10. Each frontend app follows the same internal shape: app router pages, domain-specific components, a small service layer, constants/hooks/types, and shared styling via Tailwind plus the shared UI package. This consistent structure means the architecture is replicated horizontally across MFEs rather than centralized in one frontend codebase.

11. Operationally, the repo depends on a few cross-cutting concerns that matter to the diagram: PostgreSQL for Identity persistence, JWT/refresh token auth, ASP.NET Identity for RBAC, Next.js for the browser layer, and YARP for service routing. The backend and frontend are independently runnable and independently deployable at the service/app level.

12. The most important diagram boundaries are therefore:
   - Browser → `shell` / MFE apps
   - Browser / shell API calls → Gateway
   - Gateway → Identity / Training
   - Identity → PostgreSQL
   - SharedKernel consumed by backend services as a compile-time dependency, not as a runtime service

Main entry points: [`Frontend/apps/shell`](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/shell) (Shell), [`Backend/EY.HRPlatform.Identity`](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity) (Identity), [`Backend/EY.HRPlatform.SharedKernel`](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel) (SharedKernel), [`Frontend/packages/ui`](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/packages/ui) (UI Package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_gateway["Gateway<br/>ASP.NET YARP proxy"]
  node_identity["Identity<br/>auth/api service"]
  node_training["Training<br/>course api"]
  node_sharedkernel["SharedKernel<br/>domain foundation"]
  node_identity_controller["Auth & Users<br/>controllers<br/>[Controllers]"]
  node_identity_domain["User Model<br/>identity domain<br/>[Domain]"]
  node_identity_persistence[("Identity DB<br/>ef core persistence<br/>[Persistence]")]
  node_identity_tokens["Token Service<br/>jwt service<br/>[Services]"]
  node_training_controller["Courses API<br/>web api controller<br/>[Controllers]"]
  node_cqrs["CQRS<br/>abstractions<br/>[CQRS]"]
  node_domain_base["Domain Base<br/>domain primitives<br/>[Domain]"]
  node_integration_events["Integration Events<br/>event contracts<br/>[IntegrationEvents]"]
  node_results["Results<br/>error pattern<br/>[Results]"]
end

subgraph group_frontend["Frontend"]
  node_shell["Shell<br/>next host"]
  node_core_app["Core App<br/>mfe app"]
  node_interview_app["Interview App<br/>mfe app"]
  node_learning_app["Learning App<br/>mfe app"]
  node_performance_app["Performance App<br/>mfe app"]
  node_recruitment_app["Recruitment App<br/>mfe app"]
  node_onboarding_app["Onboarding App<br/>mfe app"]
  node_ui_package["UI Package<br/>shared components"]
end

node_shell -->|"composes"| node_core_app
node_shell -->|"composes"| node_interview_app
node_shell -->|"composes"| node_learning_app
node_shell -->|"composes"| node_performance_app
node_shell -->|"composes"| node_recruitment_app
node_shell -->|"composes"| node_onboarding_app
node_core_app -->|"uses"| node_ui_package
node_interview_app -->|"uses"| node_ui_package
node_learning_app -->|"uses"| node_ui_package
node_performance_app -->|"uses"| node_ui_package
node_recruitment_app -->|"uses"| node_ui_package
node_onboarding_app -->|"uses"| node_ui_package
node_shell -->|"calls"| node_gateway
node_gateway -->|"routes"| node_identity
node_gateway -->|"routes"| node_training
node_identity -->|"exposes"| node_identity_controller
node_identity -->|"owns"| node_identity_domain
node_identity -->|"persists to"| node_identity_persistence
node_identity -->|"issues"| node_identity_tokens
node_training -->|"exposes"| node_training_controller
node_identity -->|"depends on"| node_sharedkernel
node_training -->|"depends on"| node_sharedkernel
node_sharedkernel -->|"contains"| node_cqrs
node_sharedkernel -->|"contains"| node_domain_base
node_sharedkernel -->|"contains"| node_integration_events
node_sharedkernel -->|"contains"| node_results

click node_gateway "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Gateway"
click node_identity "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity"
click node_training "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Training"
click node_sharedkernel "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel"
click node_identity_controller "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity/Controllers"
click node_identity_domain "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity/Domain"
click node_identity_persistence "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity/Infrastructure/Persistence"
click node_identity_tokens "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity/Infrastructure/Services"
click node_training_controller "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Training/Controllers"
click node_cqrs "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel/CQRS"
click node_domain_base "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel/Domain"
click node_integration_events "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel/Events/IntegrationEvents"
click node_results "https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel/Results"
click node_shell "https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/shell"
click node_core_app "https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/core"
click node_interview_app "https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/interview"
click node_learning_app "https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/learning"
click node_performance_app "https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/performance"
click node_recruitment_app "https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/recruitment"
click node_onboarding_app "https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/onboarding"
click node_ui_package "https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/packages/ui"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_identity,node_training,node_sharedkernel,node_identity_controller,node_identity_domain,node_identity_persistence,node_identity_tokens,node_training_controller,node_cqrs,node_domain_base,node_integration_events,node_results toneBlue
class node_shell,node_core_app,node_interview_app,node_learning_app,node_performance_app,node_recruitment_app,node_onboarding_app,node_ui_package toneAmber
```

## Components

### Backend

ASP.NET service-oriented monorepo

- [Gateway](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Gateway): ASP.NET YARP proxy · Single HTTP entry point; validates JWTs, adds correlation IDs, and routes traffic to backend services. · `Backend/EY.HRPlatform.Gateway`
- [Identity](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity): auth/api service · Authentication and user management service; source of truth for users, roles, JWTs, and refresh tokens. · `Backend/EY.HRPlatform.Identity`
- [Training](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Training): course api · Independent training bounded context with course APIs behind the gateway. · `Backend/EY.HRPlatform.Training`
- [SharedKernel](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel): domain foundation · Reusable backend foundation for CQRS, domain primitives, value objects, results, and integration event contracts. · `Backend/EY.HRPlatform.SharedKernel`
- [Auth & Users](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity/Controllers): controllers · Identity HTTP surface for login, register, refresh, and user operations. · `Backend/EY.HRPlatform.Identity/Controllers`
- [User Model](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity/Domain): identity domain · ApplicationUser, RefreshToken, and platform role concepts. · `Backend/EY.HRPlatform.Identity/Domain`
- [Identity DB](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity/Infrastructure/Persistence): ef core persistence · EF Core DbContext, migrations, and seeding for identity data stored in PostgreSQL. · `Backend/EY.HRPlatform.Identity/Infrastructure/Persistence`
- [Token Service](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Identity/Infrastructure/Services): jwt service · Issues and rotates JWT/refresh tokens for authentication flows. · `Backend/EY.HRPlatform.Identity/Infrastructure/Services`
- [Courses API](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.Training/Controllers): web api controller · Training HTTP surface for course-related operations. · `Backend/EY.HRPlatform.Training/Controllers`
- [CQRS](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel/CQRS): abstractions · Command/query interfaces and handlers used across backend services. · `Backend/EY.HRPlatform.SharedKernel/CQRS`
- [Domain Base](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel/Domain): domain primitives · BaseEntity, AggregateRoot, domain events, and strongly typed value objects. · `Backend/EY.HRPlatform.SharedKernel/Domain`
- [Integration Events](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel/Events/IntegrationEvents): event contracts · Event contracts such as EmployeeCreated and EmployeeDeactivated for future async integration. · `Backend/EY.HRPlatform.SharedKernel/Events/IntegrationEvents`
- [Results](https://github.com/fusion-hr-solution/fusion/blob/master/Backend/EY.HRPlatform.SharedKernel/Results): error pattern · Result and Error types for explicit success/failure handling. · `Backend/EY.HRPlatform.SharedKernel/Results`

### Frontend

Next.js/Turborepo microfrontend workspace

- [Shell](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/shell): next host · Browser-facing host that composes and routes microfrontends under path prefixes. · `Frontend/apps/shell`
- [Core App](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/core): mfe app · Shared platform experience microfrontend for core platform screens. · `Frontend/apps/core`
- [Interview App](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/interview): mfe app · Microfrontend for interview workflows and scheduling. · `Frontend/apps/interview`
- [Learning App](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/learning): mfe app · Microfrontend for courses and learning experiences. · `Frontend/apps/learning`
- [Performance App](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/performance): mfe app · Microfrontend for reviews and performance workflows. · `Frontend/apps/performance`
- [Recruitment App](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/recruitment): mfe app · Microfrontend for job openings and hiring flows. · `Frontend/apps/recruitment`
- [Onboarding App](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/apps/onboarding): mfe app · Microfrontend for new-hire onboarding flows. · `Frontend/apps/onboarding`
- [UI Package](https://github.com/fusion-hr-solution/fusion/tree/master/Frontend/packages/ui): shared components · Shared component library used across frontend apps. · `Frontend/packages/ui`

## Connections

- Shell → Core App: composes · Shell provides the host experience and routes to domain apps.
- Shell → Interview App: composes · Shell exposes the interview microfrontend under a path prefix.
- Shell → Learning App: composes · Shell exposes the learning microfrontend under a path prefix.
- Shell → Performance App: composes · Shell exposes the performance microfrontend under a path prefix.
- Shell → Recruitment App: composes · Shell exposes the recruitment microfrontend under a path prefix.
- Shell → Onboarding App: composes · Shell exposes the onboarding microfrontend under a path prefix.
- Core App → UI Package: uses · Core UI is built from shared primitives.
- Interview App → UI Package: uses · Interview UI is built from shared primitives.
- Learning App → UI Package: uses · Learning UI is built from shared primitives.
- Performance App → UI Package: uses · Performance UI is built from shared primitives.
- Recruitment App → UI Package: uses · Recruitment UI is built from shared primitives.
- Onboarding App → UI Package: uses · Onboarding UI is built from shared primitives.
- Shell → Gateway: calls · Frontend shell and MFEs send API traffic to the backend entry point.
- Gateway → Identity: routes · Gateway forwards auth and user traffic to Identity.
- Gateway → Training: routes · Gateway forwards training traffic to Training.
- Identity → Auth & Users: exposes · Identity controllers implement the public auth and user API.
- Identity → User Model: owns · Identity owns the user, token, and role domain model.
- Identity → Identity DB: persists to · Identity stores users and refresh tokens via EF Core.
- Identity → Token Service: issues · Identity uses a token service for JWT issuance and rotation.
- Training → Courses API: exposes · Training controller implements the course API surface.
- Identity → SharedKernel: depends on · Identity reuses backend primitives and contracts.
- Training → SharedKernel: depends on · Training reuses backend primitives and contracts.
- SharedKernel → CQRS: contains · CQRS interfaces and handlers define command/query boundaries.
- SharedKernel → Domain Base: contains · Domain base types and value objects live here.
- SharedKernel → Integration Events: contains · Integration event contracts are defined in the shared foundation.
- SharedKernel → Results: contains · Result/error types support consistent error handling.
