# ahmuhaisen/tsp architecture

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

- Interactive diagram: https://gitdiagram.com/ahmuhaisen/tsp
- Repository: https://github.com/ahmuhaisen/tsp

## Overview

1. **Overall shape**
   - This is a split frontend/backend monorepo for a university societies portal.
   - The system is organized as four backend layers plus one Angular client:
     - `TSP.Domain` for core business objects and domain events
     - `TPS.Application` for use cases and orchestration
     - `TPS.Infrastructure` for persistence and external integrations
     - `TSP.WebAPI` for HTTP/API composition
     - `TSP.App` for the Angular UI

2. **Frontend boundary**
   - `TSP.App` is a feature-routed Angular 19 application.
   - It is divided by user experience and role: public pages, authentication, student area, system admin area, super admin area, and public forms.
   - Shared concerns live in `common/` and reusable UI components in `components/`.
   - The UI talks to the backend through Angular services and HTTP interceptors, and also subscribes to SignalR notifications through a dedicated client service.

3. **API boundary**
   - `TSP.WebAPI` is the transport layer and main entry point for clients.
   - Controllers are split by area: authentication, shared endpoints, student area, admin area, super admin area, notifications, profiles, search, PDF, attendees, feedback, schools, ranks, and tests.
   - This layer is responsible for request validation, auth enforcement, and mapping HTTP requests to application commands/queries.

4. **Application layer structure**
   - `TPS.Application` contains the use-case layer, organized by feature areas instead of by technical type.
   - It uses a CQRS-style split: commands mutate state, queries read state.
   - The area structure mirrors the product domains: authentication, feedback, shared services, student area, admin area, super admin, and public/shared helpers.

5. **Business domain**
   - `TSP.Domain` defines the core entities and rules: users, students, faculty members, schools, departments, ranks, societies, events, membership requests, attendees, notifications, feedback, and join/leave relationships.
   - It also contains domain events such as society creation, membership changes, event scheduling, event request updates, and feedback submission.
   - These events are the main decoupling mechanism between state changes and side effects.

6. **Persistence and data model**
   - `TPS.Infrastructure/Data/ApplicationDbContext.cs` is the EF Core persistence boundary.
   - Entity configurations define the schema for the main aggregates and relationship tables, including memberships, events, approvals, notifications, and feedback summaries.
   - Migrations show that SQL Server is the primary database backend.
   - A data seeder and faker utilities exist for bootstrapping development data.

7. **Outbox and background processing**
   - Domain events are converted into outbox messages by an EF Core interceptor.
   - `ProcessOutboxMessagesJob` processes those messages asynchronously, which suggests reliable event delivery and side-effect handling outside the main request transaction.
   - This is important for architecture diagrams because it separates synchronous request handling from delayed cross-cutting work.

8. **Realtime notifications**
   - The notification system uses SignalR.
   - `NotificationHub` and `UserConnectionManager` in the application layer support live user updates.
   - Notifications are also persisted as entities, so the system has both durable notification storage and realtime push delivery.

9. **Email and document generation**
   - `TPS.Infrastructure/Emailing` is the outbound email subsystem, with templates for membership, event, society, and password-reset scenarios.
   - `PdfController` and the readme indicate PDF reporting is part of the public API surface, likely backed by application/infrastructure services.
   - These are externalized side effects driven by domain/application events and controller actions.

10. **AI feedback analysis pipeline**
   - Feedback handling is a separate subsystem with its own service and event handler.
   - The infrastructure layer includes an AI client service that integrates with Ollama and a local model.
   - The feedback feature analyzes event feedback, producing sentiment summaries and insights; this is likely triggered after submission rather than during the initial form post.

11. **Role-based business flows**
   - The application and UI are partitioned by actor:
     - students manage membership, event participation, and profiles
     - faculty/advisors manage societies and approvals
     - system admins manage societies, users, statistics, and events
     - super admins handle accounts and high-level administration
   - The same domain model is reused, but controller routes, UI routes, and application handlers are role-specific.

12. **Shared services and cross-feature read models**
   - `TPS.Application/Areas/Shared` contains read and utility services reused across roles: user, student, society, profile, search, notifications, schools, and faculty member lookup.
   - This layer acts as a shared facade for common queries and cross-cutting operations, reducing duplication across the role-specific areas.

13. **External integrations**
   - The system depends on SQL Server, JWT-based authentication, SignalR, SMTP email, and Ollama for AI.
   - The frontend is configured for Firebase Hosting and includes deployment assets and CI pipeline files, indicating the Angular app can be hosted separately from the API.

14. **How data moves**
   - Typical flow: Angular UI calls a WebAPI controller, which delegates to an application command/query, which reads/writes via Infrastructure and EF Core, which may emit domain events.
   - Domain events can then create outbox messages, trigger background jobs, send emails, push SignalR notifications, or invoke AI analysis.
   - Read-heavy screens use query DTOs rather than domain entities, which keeps the API responses shaped for the UI and reporting views.

Main entry points: [`TSP.App/src/app/app.component.ts`](https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/app.component.ts) (App shell), [`TPS.Application/Areas`](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas) (CQRS layer), [`TPS.Application/Areas/Shared`](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas/Shared) (Shared services), [`TPS.Infrastructure/Data/ApplicationDbContext.cs`](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Infrastructure/Data/ApplicationDbContext.cs) (EF Core DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["TSP.App"]
  node_app_shell["App shell<br/>Angular root<br/>[app.component.ts]"]
  node_app_common["Common<br/>shared client<br/>[common]"]
  node_app_student["Student area<br/>feature UI<br/>[student-area]"]
  node_app_admin["System admin<br/>feature UI<br/>[system-admin-area]"]
  node_app_super["Super admin<br/>feature UI<br/>[super-admin]"]
  node_app_public["Public forms<br/>feature UI<br/>[public-forms]"]
end

subgraph group_api["TSP.WebAPI"]
  node_api_auth["Auth API<br/>controller area"]
  node_api_student["Student API<br/>controller area<br/>[StudentArea]"]
  node_api_admin["Admin API<br/>controller area<br/>[AdminArea]"]
  node_api_super["Super API<br/>controller area<br/>[SuperAdminArea]"]
  node_api_shared["Shared API<br/>controller surface<br/>[Controllers]"]
end

subgraph group_application["TPS.Application"]
  node_app_cqrs["CQRS layer<br/>use cases<br/>[Areas]"]
  node_app_shared["Shared services<br/>application facade<br/>[Shared]"]
  node_app_events["Event handlers<br/>domain reactions<br/>[Areas]"]
  node_app_realtime(("Realtime hub<br/>SignalR support<br/>[NotificationHub.cs]"))
  node_app_super_accounts["Accounts service<br/>admin use case<br/>[AccountsService.cs]"]
end

subgraph group_domain["TSP.Domain"]
  node_domain_entities[("Entities<br/>domain model<br/>[Entities]")]
  node_domain_events{{"Domain events<br/>[Events]"}}
  node_domain_primitives["Primitives<br/>domain base<br/>[Primitives]"]
end

subgraph group_infrastructure["TPS.Infrastructure"]
  node_infra_db[("EF Core DB<br/>persistence boundary")]
  node_infra_outbox["Outbox job<br/>background worker"]
  node_infra_external["Outbound services<br/>integrations<br/>[EmailService.cs]"]
end

node_app_shell -->|"uses"| node_app_common
node_app_shell -->|"routes to"| node_app_student
node_app_shell -->|"routes to"| node_app_admin
node_app_shell -->|"routes to"| node_app_super
node_app_shell -->|"routes to"| node_app_public
node_app_student -->|"calls"| node_api_student
node_app_admin -->|"calls"| node_api_admin
node_app_super -->|"calls"| node_api_super
node_app_public -->|"calls"| node_api_shared
node_app_common -->|"subscribes"| node_app_realtime
node_api_auth -->|"delegates to"| node_app_cqrs
node_api_student -->|"delegates to"| node_app_cqrs
node_api_admin -->|"delegates to"| node_app_cqrs
node_api_super -->|"delegates to"| node_app_super_accounts
node_api_shared -->|"delegates to"| node_app_shared
node_app_cqrs -->|"uses"| node_domain_entities
node_app_cqrs -->|"raises"| node_domain_events
node_app_events -->|"triggers"| node_infra_external
node_app_events -->|"pushes"| node_app_realtime
node_domain_events -->|"serialized by"| node_infra_outbox
node_infra_outbox -->|"delivers"| node_infra_external
node_infra_db -->|"maps"| node_domain_entities
node_infra_db -->|"stores"| node_infra_outbox
node_app_shared -->|"reads"| node_infra_db
node_app_shared -->|"projects from"| node_domain_entities

click node_app_shell "https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/app.component.ts"
click node_app_common "https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/common"
click node_app_student "https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/areas/student-area"
click node_app_admin "https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/areas/system-admin-area"
click node_app_super "https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/areas/super-admin"
click node_app_public "https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/areas/public-forms"
click node_api_auth "https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers/AuthenticationController.cs"
click node_api_student "https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers/StudentArea"
click node_api_admin "https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers/AdminArea"
click node_api_super "https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers/SuperAdminArea"
click node_api_shared "https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers"
click node_app_cqrs "https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas"
click node_app_shared "https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas/Shared"
click node_app_events "https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas"
click node_app_realtime "https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/SignalR/NotificationHub.cs"
click node_app_super_accounts "https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas/SuperAdmin/AccountsService.cs"
click node_domain_entities "https://github.com/ahmuhaisen/tsp/blob/master/TSP.Domain/Entities"
click node_domain_events "https://github.com/ahmuhaisen/tsp/blob/master/TSP.Domain/Events"
click node_domain_primitives "https://github.com/ahmuhaisen/tsp/blob/master/TSP.Domain/Primitives"
click node_infra_db "https://github.com/ahmuhaisen/tsp/blob/master/TPS.Infrastructure/Data/ApplicationDbContext.cs"
click node_infra_outbox "https://github.com/ahmuhaisen/tsp/blob/master/TPS.Infrastructure/BackgroundJobs/ProcessOutboxMessagesJob.cs"
click node_infra_external "https://github.com/ahmuhaisen/tsp/blob/master/TPS.Infrastructure/Emailing/EmailService.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_app_shell,node_app_common,node_app_student,node_app_admin,node_app_super,node_app_public toneBlue
class node_api_auth,node_api_student,node_api_admin,node_api_super,node_api_shared toneAmber
class node_app_cqrs,node_app_shared,node_app_events,node_app_realtime,node_app_super_accounts toneMint
class node_domain_entities,node_domain_events,node_domain_primitives toneRose
class node_infra_db,node_infra_outbox,node_infra_external toneIndigo
```

## Components

### TSP.App

Angular client and routed UI areas

- [App shell](https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/app.component.ts): Angular root · Bootstraps the Angular app, routing, and global layout · `TSP.App/src/app/app.component.ts`
- [Common](https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/common): shared client · Cross-cutting guards, services, pipes, and types shared by UI areas · `TSP.App/src/app/common`
- [Student area](https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/areas/student-area): feature UI · Student-facing pages, services, and shared nav for memberships, events, and profiles · `TSP.App/src/app/areas/student-area`
- [System admin](https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/areas/system-admin-area): feature UI · System admin pages for societies, events, statistics, and user management · `TSP.App/src/app/areas/system-admin-area`
- [Super admin](https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/areas/super-admin): feature UI · Super admin pages and services for accounts and society administration · `TSP.App/src/app/areas/super-admin`
- [Public forms](https://github.com/ahmuhaisen/tsp/blob/master/TSP.App/src/app/areas/public-forms): feature UI · Public attendance and feedback flows exposed outside authenticated areas · `TSP.App/src/app/areas/public-forms`

### TSP.WebAPI

HTTP entry point and transport layer

- [Auth API](https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers/AuthenticationController.cs): controller area · Authentication and login/reset endpoints · `TSP.WebAPI/Controllers/AuthenticationController.cs`
- [Student API](https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers/StudentArea): controller area · Student-area endpoints for home, societies, events, and student actions · `TSP.WebAPI/Controllers/StudentArea`
- [Admin API](https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers/AdminArea): controller area · Admin-area endpoints for home, societies, events, advisors, and statistics · `TSP.WebAPI/Controllers/AdminArea`
- [Super API](https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers/SuperAdminArea): controller area · Super-admin endpoints for accounts and society administration · `TSP.WebAPI/Controllers/SuperAdminArea`
- [Shared API](https://github.com/ahmuhaisen/tsp/blob/master/TSP.WebAPI/Controllers): controller surface · Shared endpoints for profiles, search, schools, ranks, notifications, PDF, attendees, feedback, and tests · `TSP.WebAPI/Controllers`

### TPS.Application

Use-case orchestration and shared services

- [CQRS layer](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas): use cases · Command/query handlers and DTO contracts organized by feature area · `TPS.Application/Areas`
- [Shared services](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas/Shared): application facade · Reusable lookup, profile, search, user, society, student, and notification services · `TPS.Application/Areas/Shared`
- [Event handlers](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas): domain reactions · Handlers that react to domain events and trigger side effects or projections · `TPS.Application/Areas`
- [Realtime hub](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/SignalR/NotificationHub.cs): SignalR support · Notification hub and connection tracking for live updates · `TPS.Application/SignalR/NotificationHub.cs`
- [Accounts service](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Application/Areas/SuperAdmin/AccountsService.cs): admin use case · Super-admin account workflow service · `TPS.Application/Areas/SuperAdmin/AccountsService.cs`

### TSP.Domain

Core entities, enums, and domain events

- [Entities](https://github.com/ahmuhaisen/tsp/blob/master/TSP.Domain/Entities): domain model · Users, students, societies, events, memberships, notifications, and feedback entities · `TSP.Domain/Entities`
- [Domain events](https://github.com/ahmuhaisen/tsp/blob/master/TSP.Domain/Events): domain events · Business events for society, event, membership, and feedback changes · `TSP.Domain/Events`
- [Primitives](https://github.com/ahmuhaisen/tsp/blob/master/TSP.Domain/Primitives): domain base · Base entity and domain-event primitives plus shared result/error types · `TSP.Domain/Primitives`

### TPS.Infrastructure

Persistence, outbox, email, AI, and jobs

- [EF Core DB](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Infrastructure/Data/ApplicationDbContext.cs): persistence boundary · ApplicationDbContext, entity configurations, migrations, seed data, and outbox storage · `TPS.Infrastructure/Data/ApplicationDbContext.cs`
- [Outbox job](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Infrastructure/BackgroundJobs/ProcessOutboxMessagesJob.cs): background worker · Converts domain events to outbox messages and processes them asynchronously · `TPS.Infrastructure/BackgroundJobs/ProcessOutboxMessagesJob.cs`
- [Outbound services](https://github.com/ahmuhaisen/tsp/blob/master/TPS.Infrastructure/Emailing/EmailService.cs): integrations · Email, AI client, and other external side-effect services · `TPS.Infrastructure/Emailing/EmailService.cs`

## Connections

- App shell → Common: uses · Root app consumes shared UI services and guards
- App shell → Student area: routes to · Feature routing exposes student experience
- App shell → System admin: routes to · Feature routing exposes system admin experience
- App shell → Super admin: routes to · Feature routing exposes super admin experience
- App shell → Public forms: routes to · Feature routing exposes public forms
- Student area → Student API: calls · Student pages use student-area API endpoints
- System admin → Admin API: calls · Admin pages use admin-area API endpoints
- Super admin → Super API: calls · Super admin pages use super-admin API endpoints
- Public forms → Shared API: calls · Public forms call shared endpoints such as attendance and feedback
- Common → Realtime hub: subscribes · Client notification service connects to SignalR
- Auth API → CQRS layer: delegates to · Controllers map requests to authentication use cases
- Student API → CQRS layer: delegates to · Student controllers invoke commands and queries
- Admin API → CQRS layer: delegates to · Admin controllers invoke commands and queries
- Super API → Accounts service: delegates to · Super-admin accounts controller uses dedicated service
- Shared API → Shared services: delegates to · Shared controllers use facades for profiles, search, schools, and notifications
- CQRS layer → Entities: uses · Use cases operate on domain entities and DTOs
- CQRS layer → Domain events: raises · Commands produce domain events for downstream side effects
- Event handlers → Outbound services: triggers · Event handlers send email or other outbound effects
- Event handlers → Realtime hub: pushes · Event handlers update live notification connections
- Domain events → Outbox job: serialized by · EF interceptor converts domain events into outbox messages
- Outbox job → Outbound services: delivers · Background processing sends delayed side effects
- EF Core DB → Entities: maps · EF Core schema persists the domain model
- EF Core DB → Outbox job: stores · Outbox messages are persisted alongside application data
- Shared services → EF Core DB: reads · Shared read services query the database via application abstractions
- Shared services → Entities: projects from · Read models are shaped from domain data
