# osamaakiladev/majlis-app architecture

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

- Interactive diagram: https://gitdiagram.com/osamaakiladev/majlis-app
- Repository: https://github.com/osamaakiladev/majlis-app

## Overview

Majlis is a university club and event management product. Students and staff use the Next.js web app to discover clubs and events, manage membership and event participation, and receive attendance records and certificates; administrators manage users and departments. The NestJS API handles authentication, permissions, domain operations, and persistence, with shared Zod contracts between packages. The README identifies PostgreSQL and Supabase image storage. Web-to-API wiring and several unsampled domain implementations are inferred only at a high level; their links are dashed where source evidence is unavailable.

Main entry points: [`apps/web/src/lib/api.ts`](https://github.com/osamaakiladev/majlis-app/blob/main/apps/web/src/lib/api.ts) (Web API client), [`apps/api/src/clubs/clubs.service.ts`](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/clubs/clubs.service.ts) (Club management), [`apps/api/src/prisma/transaction.host.ts`](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/prisma/transaction.host.ts) (Transaction host), [`packages/contracts/src`](https://github.com/osamaakiladev/majlis-app/tree/main/packages/contracts/src) (Zod contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web application"]
  node_webapi["Web API client<br/>[api.ts]"]
end

subgraph group_api["API domains"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_club["Club management<br/>[clubs.service.ts]"]
  node_membership["Membership and teams"]
  node_events["Event management<br/>[events.service.ts]"]
  node_registration["Event registration"]
  node_attendance["Attendance"]
  node_certificates["Certificates"]
  node_users["User administration<br/>[users.service.ts]"]
  node_departments["Departments"]
  node_reporting["Reporting"]
  node_audit["Audit trail<br/>[audit.service.ts]"]
  node_notifications["Notifications"]
end

subgraph group_shared["Shared contracts"]
  node_contracts["Zod contracts"]
end

subgraph group_infra["Persistence and integrations"]
  node_transaction["Transaction host"]
  node_postgres[("PostgreSQL")]
  node_storage["Image storage<br/>[storage.service.ts]"]
end

node_people(("Students and staff"))
node_supabase["Supabase Storage"]
node_email["Email provider"]

node_people -->|"uses"| node_webapp
node_webapp -.->|"requests data"| node_webapi
node_webapi -.->|"calls API"| node_auth
node_webapi -.->|"calls API"| node_club
node_webapi -.->|"calls API"| node_events
node_webapi -.->|"calls API"| node_attendance
node_club -.->|"uses"| node_membership
node_events -.->|"uses"| node_registration
node_registration -.->|"enables check-in"| node_attendance
node_attendance -->|"invokes"| node_certificates
node_auth -->|"requests delivery"| node_notifications
node_club -->|"requests upload"| node_storage
node_storage -->|"signs uploads"| node_supabase
node_club -.->|"records changes"| node_audit
node_membership -.->|"records changes"| node_audit
node_certificates -->|"records changes"| node_audit
node_certificates -->|"notifies users"| node_notifications
node_notifications -->|"delivers email"| node_email
node_attendance -->|"runs transactions"| node_transaction
node_auth -->|"queries and writes"| node_transaction
node_audit -->|"writes audit rows"| node_transaction
node_notifications -->|"stores notifications"| node_transaction
node_transaction -.->|"persists data"| node_postgres
node_webapp -->|"shares schemas"| node_contracts
node_auth -->|"uses schemas"| node_contracts
node_club -->|"uses schemas"| node_contracts
node_events -->|"uses schemas"| node_contracts
node_users -->|"uses schemas"| node_contracts

click node_webapp "https://github.com/osamaakiladev/majlis-app/tree/main/apps/web/src/app"
click node_webapi "https://github.com/osamaakiladev/majlis-app/blob/main/apps/web/src/lib/api.ts"
click node_auth "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/auth/auth.service.ts"
click node_club "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/clubs/clubs.service.ts"
click node_membership "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/clubs/membership/membership.service.ts"
click node_events "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/events/events.service.ts"
click node_registration "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/events/registrations.service.ts"
click node_attendance "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/attendance/attendance.service.ts"
click node_certificates "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/certificates/certificates.service.ts"
click node_users "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/users/users.service.ts"
click node_departments "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/departments/departments.service.ts"
click node_reporting "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/reporting/reporting.service.ts"
click node_audit "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/audit/audit.service.ts"
click node_notifications "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/notifications/notification.service.ts"
click node_contracts "https://github.com/osamaakiladev/majlis-app/tree/main/packages/contracts/src"
click node_transaction "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/prisma/transaction.host.ts"
click node_storage "https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/storage/storage.service.ts"

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_webapp,node_webapi toneBlue
class node_auth,node_club,node_membership,node_events,node_registration,node_attendance,node_certificates,node_users,node_departments,node_reporting,node_audit,node_notifications,node_supabase toneAmber
class node_contracts toneMint
class node_transaction,node_postgres,node_storage toneRose
class node_people,node_email toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/osamaakiladev/majlis-app/tree/main/apps/web/src/app): `apps/web/src/app`
- [Web API client](https://github.com/osamaakiladev/majlis-app/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### API domains

- [Authentication](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/auth/auth.service.ts): `apps/api/src/auth/auth.service.ts`
- [Club management](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/clubs/clubs.service.ts): `apps/api/src/clubs/clubs.service.ts`
- [Membership and teams](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/clubs/membership/membership.service.ts): `apps/api/src/clubs/membership/membership.service.ts`
- [Event management](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/events/events.service.ts): `apps/api/src/events/events.service.ts`
- [Event registration](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/events/registrations.service.ts): `apps/api/src/events/registrations.service.ts`
- [Attendance](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/attendance/attendance.service.ts): `apps/api/src/attendance/attendance.service.ts`
- [Certificates](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/certificates/certificates.service.ts): `apps/api/src/certificates/certificates.service.ts`
- [User administration](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/users/users.service.ts): `apps/api/src/users/users.service.ts`
- [Departments](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/departments/departments.service.ts): `apps/api/src/departments/departments.service.ts`
- [Reporting](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/reporting/reporting.service.ts): `apps/api/src/reporting/reporting.service.ts`
- [Audit trail](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/audit/audit.service.ts): `apps/api/src/audit/audit.service.ts`
- [Notifications](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/notifications/notification.service.ts): `apps/api/src/notifications/notification.service.ts`

### Shared contracts

- [Zod contracts](https://github.com/osamaakiladev/majlis-app/tree/main/packages/contracts/src): `packages/contracts/src`

### Persistence and integrations

- [Transaction host](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/prisma/transaction.host.ts): `apps/api/src/prisma/transaction.host.ts`
- **PostgreSQL**
- [Image storage](https://github.com/osamaakiladev/majlis-app/blob/main/apps/api/src/storage/storage.service.ts): `apps/api/src/storage/storage.service.ts`

### Other components

- **Students and staff**
- **Supabase Storage**
- **Email provider**

## Connections

- Students and staff → Web application: uses (evidence: `README.md`)
- Web application → Web API client: requests data
- Web API client → Authentication: calls API
- Web API client → Club management: calls API
- Web API client → Event management: calls API
- Web API client → Attendance: calls API
- Club management → Membership and teams: uses
- Event management → Event registration: uses
- Event registration → Attendance: enables check-in
- Attendance → Certificates: invokes (evidence: `apps/api/src/attendance/attendance.service.ts`)
- Authentication → Notifications: requests delivery (evidence: `apps/api/src/auth/auth.service.ts`)
- Club management → Image storage: requests upload (evidence: `apps/api/src/clubs/clubs.service.ts`)
- Image storage → Supabase Storage: signs uploads (evidence: `apps/api/src/storage/storage.service.ts`)
- Club management → Audit trail: records changes (evidence: `apps/api/src/clubs/clubs.service.ts`)
- Membership and teams → Audit trail: records changes (evidence: `apps/api/src/clubs/membership/membership.service.ts`)
- Certificates → Audit trail: records changes (evidence: `apps/api/src/certificates/certificates.service.ts`)
- Certificates → Notifications: notifies users (evidence: `apps/api/src/certificates/certificates.service.ts`)
- Notifications → Email provider: delivers email (evidence: `apps/api/src/notifications/notification.service.ts`)
- Attendance → Transaction host: runs transactions (evidence: `apps/api/src/attendance/attendance.service.ts`)
- Authentication → Transaction host: queries and writes (evidence: `apps/api/src/auth/auth.service.ts`)
- Audit trail → Transaction host: writes audit rows (evidence: `apps/api/src/audit/audit.service.ts`)
- Notifications → Transaction host: stores notifications (evidence: `apps/api/src/notifications/notification.service.ts`)
- Transaction host → PostgreSQL: persists data
- Web application → Zod contracts: shares schemas (evidence: `README.md`)
- Authentication → Zod contracts: uses schemas (evidence: `apps/api/src/auth/auth.service.ts`)
- Club management → Zod contracts: uses schemas (evidence: `apps/api/src/clubs/clubs.service.ts`)
- Event management → Zod contracts: uses schemas
- User administration → Zod contracts: uses schemas
