# 1babii1/ds architecture

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

- Interactive diagram: https://gitdiagram.com/1babii1/ds
- Repository: https://github.com/1babii1/ds

## Overview

dsPortfolio is a distributed organization-management platform, not a single application: its main user workflow manages departments, positions, locations, and employees, with rewards and other capabilities alongside it. The README also documents account security, notifications, cross-entity search, an AI assistant that proposes user-approved changes, and audit-based organization history. The graph captures those documented product branches and a few source-index-supported internal layers. Most service wiring was not sampled, so undocumented connections are omitted rather than inferred.

Main entry points: [`frontend`](https://github.com/1babii1/ds/tree/main/frontend) (Web application), [`backend/McpServer`](https://github.com/1babii1/ds/tree/main/backend/McpServer) (Assistant tools), [`backend/EmployeeService/EmployeeService.Web/Controllers/EmployeeController.cs`](https://github.com/1babii1/ds/blob/main/backend/EmployeeService/EmployeeService.Web/Controllers/EmployeeController.cs) (Employee API), [`backend/AuditService/AuditService.Web/Controllers/AuditController.cs`](https://github.com/1babii1/ds/blob/main/backend/AuditService/AuditService.Web/Controllers/AuditController.cs) (Audit and history API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_auth["Authentication<br/>[AuthService.Web]"]
end

subgraph group_organization["Organization management"]
  node_directory_api["Directory API"]
  node_directory_domain["Directory model<br/>[Department.cs]"]
  node_directory_store[("Directory persistence")]
  node_employee_api["Employee API"]
  node_employee_commands["Employee commands<br/>[Commands]"]
  node_employee_domain["Employee model<br/>[Employee.cs]"]
end

subgraph group_engagement["Rewards and notifications"]
  node_rewards[("Rewards ledger")]
  node_notifications["Notifications"]
end

subgraph group_discovery["Search and history"]
  node_search["Cross-entity search"]
  node_audit_api["Audit and history API<br/>[AuditController.cs]"]
  node_audit_store[("Audit event store<br/>[AuditDbContext.cs]")]
  node_org_replay["Organization replay<br/>[OrgReplay.cs]"]
end

subgraph group_experience["User experience"]
  node_frontend["Web application"]
  node_assistant["AI assistant route<br/>[route.ts]"]
  node_mcp["Assistant tools"]
end

node_user(("User"))
node_event_broker["Event broker"]

node_user -.->|"uses"| node_frontend
node_frontend -.->|"authenticates"| node_auth
node_frontend -.->|"manages organization"| node_directory_api
node_frontend -.->|"manages employees"| node_employee_api
node_frontend -.->|"uses rewards"| node_rewards
node_frontend -.->|"receives updates"| node_notifications
node_frontend -.->|"searches"| node_search
node_frontend -->|"views history"| node_audit_api
node_user -->|"requests proposals"| node_assistant
node_assistant -.->|"uses tools"| node_mcp
node_mcp -->|"resolves organization data"| node_directory_api
node_mcp -->|"proposes employee changes"| node_employee_api
node_mcp -->|"proposes grants"| node_rewards
node_mcp -->|"reads snapshots"| node_audit_api
node_directory_api -->|"uses model"| node_directory_domain
node_directory_store -->|"persists entities"| node_directory_domain
node_employee_api -->|"dispatches commands"| node_employee_commands
node_employee_commands -.->|"updates employees"| node_employee_domain
node_employee_api -.->|"looks up directory"| node_directory_api
node_employee_api -->|"returns wallet copy"| node_rewards
node_event_broker -->|"delivers events"| node_audit_store
node_audit_api -->|"reads events"| node_audit_store
node_audit_api -->|"rebuilds snapshot"| node_org_replay
node_event_broker -.->|"delivers updates"| node_notifications
node_event_broker -.->|"feeds index"| node_search

click node_frontend "https://github.com/1babii1/ds/tree/main/frontend"
click node_assistant "https://github.com/1babii1/ds/blob/main/frontend/app/api/assistant/route.ts"
click node_mcp "https://github.com/1babii1/ds/tree/main/backend/McpServer"
click node_auth "https://github.com/1babii1/ds/tree/main/backend/AuthService/AuthService.Web"
click node_directory_api "https://github.com/1babii1/ds/tree/main/backend/DirectoryService/DirectoryService"
click node_directory_domain "https://github.com/1babii1/ds/blob/main/backend/DirectoryService/DirectoryService.Domain/Departments/Department.cs"
click node_directory_store "https://github.com/1babii1/ds/blob/main/backend/DirectoryService/DirectoryService.Infrastructure.Postgres/DirectoryServiceDbContext.cs"
click node_employee_api "https://github.com/1babii1/ds/blob/main/backend/EmployeeService/EmployeeService.Web/Controllers/EmployeeController.cs"
click node_employee_commands "https://github.com/1babii1/ds/tree/main/backend/EmployeeService/EmployeeService.Application/Employees/Commands"
click node_employee_domain "https://github.com/1babii1/ds/blob/main/backend/EmployeeService/EmployeeService.Domain/Employee.cs"
click node_rewards "https://github.com/1babii1/ds/blob/main/backend/RewardsService/RewardsService.Web/Controllers/RewardsController.cs"
click node_notifications "https://github.com/1babii1/ds/blob/main/backend/NotificationService/NotificationService.Web/Controllers/NotificationsController.cs"
click node_search "https://github.com/1babii1/ds/tree/main/backend/SearchService"
click node_audit_api "https://github.com/1babii1/ds/blob/main/backend/AuditService/AuditService.Web/Controllers/AuditController.cs"
click node_audit_store "https://github.com/1babii1/ds/blob/main/backend/AuditService/AuditService.Infrastructure/AuditDbContext.cs"
click node_org_replay "https://github.com/1babii1/ds/blob/main/backend/AuditService/AuditService.Domain/OrgReplay.cs"

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_auth,node_user toneBlue
class node_directory_api,node_directory_domain,node_directory_store,node_employee_api,node_employee_commands,node_employee_domain toneAmber
class node_rewards,node_notifications toneMint
class node_search,node_audit_api,node_audit_store,node_org_replay toneRose
class node_frontend,node_assistant,node_mcp,node_event_broker toneIndigo
```

## Components

### Identity and access

- [Authentication](https://github.com/1babii1/ds/tree/main/backend/AuthService/AuthService.Web): `backend/AuthService/AuthService.Web`

### Organization management

- [Directory API](https://github.com/1babii1/ds/tree/main/backend/DirectoryService/DirectoryService): `backend/DirectoryService/DirectoryService`
- [Directory model](https://github.com/1babii1/ds/blob/main/backend/DirectoryService/DirectoryService.Domain/Departments/Department.cs): `backend/DirectoryService/DirectoryService.Domain/Departments/Department.cs`
- [Directory persistence](https://github.com/1babii1/ds/blob/main/backend/DirectoryService/DirectoryService.Infrastructure.Postgres/DirectoryServiceDbContext.cs): `backend/DirectoryService/DirectoryService.Infrastructure.Postgres/DirectoryServiceDbContext.cs`
- [Employee API](https://github.com/1babii1/ds/blob/main/backend/EmployeeService/EmployeeService.Web/Controllers/EmployeeController.cs): `backend/EmployeeService/EmployeeService.Web/Controllers/EmployeeController.cs`
- [Employee commands](https://github.com/1babii1/ds/tree/main/backend/EmployeeService/EmployeeService.Application/Employees/Commands): `backend/EmployeeService/EmployeeService.Application/Employees/Commands`
- [Employee model](https://github.com/1babii1/ds/blob/main/backend/EmployeeService/EmployeeService.Domain/Employee.cs): `backend/EmployeeService/EmployeeService.Domain/Employee.cs`

### Rewards and notifications

- [Rewards ledger](https://github.com/1babii1/ds/blob/main/backend/RewardsService/RewardsService.Web/Controllers/RewardsController.cs): `backend/RewardsService/RewardsService.Web/Controllers/RewardsController.cs`
- [Notifications](https://github.com/1babii1/ds/blob/main/backend/NotificationService/NotificationService.Web/Controllers/NotificationsController.cs): `backend/NotificationService/NotificationService.Web/Controllers/NotificationsController.cs`

### Search and history

- [Cross-entity search](https://github.com/1babii1/ds/tree/main/backend/SearchService): `backend/SearchService`
- [Audit and history API](https://github.com/1babii1/ds/blob/main/backend/AuditService/AuditService.Web/Controllers/AuditController.cs): `backend/AuditService/AuditService.Web/Controllers/AuditController.cs`
- [Audit event store](https://github.com/1babii1/ds/blob/main/backend/AuditService/AuditService.Infrastructure/AuditDbContext.cs): `backend/AuditService/AuditService.Infrastructure/AuditDbContext.cs`
- [Organization replay](https://github.com/1babii1/ds/blob/main/backend/AuditService/AuditService.Domain/OrgReplay.cs): `backend/AuditService/AuditService.Domain/OrgReplay.cs`

### User experience

- [Web application](https://github.com/1babii1/ds/tree/main/frontend): `frontend`
- [AI assistant route](https://github.com/1babii1/ds/blob/main/frontend/app/api/assistant/route.ts): `frontend/app/api/assistant/route.ts`
- [Assistant tools](https://github.com/1babii1/ds/tree/main/backend/McpServer): `backend/McpServer`

### Other components

- **User**
- **Event broker**

## Connections

- User → Web application: uses
- Web application → Authentication: authenticates
- Web application → Directory API: manages organization
- Web application → Employee API: manages employees
- Web application → Rewards ledger: uses rewards
- Web application → Notifications: receives updates
- Web application → Cross-entity search: searches
- Web application → Audit and history API: views history (evidence: `README.md`)
- User → AI assistant route: requests proposals (evidence: `README.md`)
- AI assistant route → Assistant tools: uses tools
- Assistant tools → Directory API: resolves organization data (evidence: `README.md`)
- Assistant tools → Employee API: proposes employee changes (evidence: `README.md`)
- Assistant tools → Rewards ledger: proposes grants (evidence: `README.md`)
- Assistant tools → Audit and history API: reads snapshots (evidence: `README.md`)
- Directory API → Directory model: uses model (evidence: `backend/DirectoryService/DirectoryService/Controllers/DepartmentController.cs`)
- Directory persistence → Directory model: persists entities (evidence: `backend/DirectoryService/DirectoryService.Infrastructure.Postgres/DirectoryServiceDbContext.cs`)
- Employee API → Employee commands: dispatches commands (evidence: `backend/EmployeeService/EmployeeService.Web/Controllers/EmployeeController.cs`)
- Employee commands → Employee model: updates employees (evidence: `backend/EmployeeService/EmployeeService.Application/Employees/Commands/HireEmployeeHandler.cs`)
- Employee API → Directory API: looks up directory
- Employee API → Rewards ledger: returns wallet copy (evidence: `backend/EmployeeService/EmployeeService.Web/Controllers/EmployeeController.cs`)
- Event broker → Audit event store: delivers events (evidence: `README.md`)
- Audit and history API → Audit event store: reads events (evidence: `backend/AuditService/AuditService.Web/Controllers/AuditController.cs`)
- Audit and history API → Organization replay: rebuilds snapshot (evidence: `backend/AuditService/AuditService.Web/Controllers/AuditController.cs`)
- Event broker → Notifications: delivers updates
- Event broker → Cross-entity search: feeds index
