How ahmuhaisen/tsp works
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: app.component.ts App shell · Areas CQRS layer · Shared Shared services · ApplicationDbContext.cs EF Core DB
Components 22
TSP.App
Angular client and routed UI areas
- App shell · Bootstraps the Angular app, routing, and global layout
TSP.App/src/app/app.component.ts - Common · Cross-cutting guards, services, pipes, and types shared by UI areas
TSP.App/src/app/common - Student area · Student-facing pages, services, and shared nav for memberships, events, and profiles
TSP.App/src/app/areas/student-area - System admin · System admin pages for societies, events, statistics, and user management
TSP.App/src/app/areas/system-admin-area - Super admin · Super admin pages and services for accounts and society administration
TSP.App/src/app/areas/super-admin - Public forms · 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 · Authentication and login/reset endpoints
TSP.WebAPI/Controllers/AuthenticationController.cs - Student API · Student-area endpoints for home, societies, events, and student actions
TSP.WebAPI/Controllers/StudentArea - Admin API · Admin-area endpoints for home, societies, events, advisors, and statistics
TSP.WebAPI/Controllers/AdminArea - Super API · Super-admin endpoints for accounts and society administration
TSP.WebAPI/Controllers/SuperAdminArea - Shared API · 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 · Command/query handlers and DTO contracts organized by feature area
TPS.Application/Areas - Shared services · Reusable lookup, profile, search, user, society, student, and notification services
TPS.Application/Areas/Shared - Event handlers · Handlers that react to domain events and trigger side effects or projections
TPS.Application/Areas - Realtime hub · Notification hub and connection tracking for live updates
TPS.Application/SignalR/NotificationHub.cs - Accounts service · Super-admin account workflow service
TPS.Application/Areas/SuperAdmin/AccountsService.cs
TSP.Domain
Core entities, enums, and domain events
- Entities · Users, students, societies, events, memberships, notifications, and feedback entities
TSP.Domain/Entities - Domain events · Business events for society, event, membership, and feedback changes
TSP.Domain/Events - Primitives · 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 · ApplicationDbContext, entity configurations, migrations, seed data, and outbox storage
TPS.Infrastructure/Data/ApplicationDbContext.cs - Outbox job · Converts domain events to outbox messages and processes them asynchronously
TPS.Infrastructure/BackgroundJobs/ProcessOutboxMessagesJob.cs - Outbound services · Email, AI client, and other external side-effect services
TPS.Infrastructure/Emailing/EmailService.cs
Connections 25
- 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