# malek-shammout/hamak-ai-robotics-club-platform architecture

> Architecture diagram of the GitHub repository malek-shammout/hamak-ai-robotics-club-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/malek-shammout/hamak-ai-robotics-club-platform
- Repository: https://github.com/malek-shammout/hamak-ai-robotics-club-platform

## Overview

HMK is a bilingual, role-governed club operations platform. Members discover opportunities, apply and complete screening, then progress through learning, equipment custody, clearance, and certification; staff administer those workflows alongside consultations and published content. The graph emphasizes that member journey and major operational branches. README documents database-enforced authorization and storage behavior; sampled files show selected action, query, and certificate routes, so unsampled feature wiring is not inferred.

Main entry points: [`src/app/[locale]`](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/tree/main/src/app/%5Blocale%5D) (Localized app routes), [`src/app/[locale]/staff/page.tsx`](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/%5Blocale%5D/staff/page.tsx) (Staff workspace), [`src/lib/lms/actions.ts`](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/lms/actions.ts) (Learning and attendance), [`src/lib/requisitions/actions.ts`](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/requisitions/actions.ts) (Hardware requisitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Bilingual experience"]
  node_localized["Localized app routes"]
  node_routing["Locale routing<br/>[routing.ts]"]
  node_publiccontent["Public discovery<br/>[public.ts]"]
  node_authpages["Registration and login<br/>[page.tsx]"]
end

subgraph group_participation["Admissions and learning"]
  node_applications["Application workflow<br/>[actions.ts]"]
  node_readiness["Readiness scoring"]
  node_allocation["Offers and allocation<br/>[staff-actions.ts]"]
  node_assessment["Screening and grading<br/>[actions.ts]"]
  node_lms["Learning and attendance<br/>[actions.ts]"]
  node_certificates["Certificate issuance<br/>[issue-document.ts]"]
  node_certdelivery["Certificate delivery<br/>[route.ts]"]
end

subgraph group_operations["Club operations"]
  node_consultations["Consultations<br/>[actions.ts]"]
  node_requisitions["Hardware requisitions<br/>[actions.ts]"]
  node_logistics["Custody and liabilities<br/>[actions.ts]"]
  node_clearance["Completion clearance<br/>[actions.ts]"]
  node_authoring["Editorial workflow<br/>[actions.ts]"]
  node_staffroutes["Staff workspace<br/>[page.tsx]"]
end

subgraph group_platform["Identity and data"]
  node_authactions["Authentication actions<br/>[actions.ts]"]
  node_callback["Email confirmation<br/>[route.ts]"]
  node_db[("PostgreSQL and RPC")]
  node_serverclient["RLS-bound server client<br/>[server.ts]"]
end

node_member(("Member / visitor"))
node_supaauth{{"Supabase Auth"}}
node_storage[("Private certificate storage")]

node_member -->|"browses / submits"| node_localized
node_localized -->|"resolves locale"| node_routing
node_localized -->|"loads discovery"| node_publiccontent
node_localized -->|"registers / signs in"| node_authpages
node_authpages -->|"invokes"| node_authactions
node_authactions -->|"authenticates"| node_supaauth
node_callback -->|"exchanges code"| node_supaauth
node_callback -->|"redirects"| node_localized
node_localized -->|"submits application"| node_applications
node_applications -->|"writes application"| node_db
node_applications -.->|"requests scoring"| node_readiness
node_readiness -->|"computes readiness"| node_db
node_staffroutes -->|"runs allocation"| node_allocation
node_allocation -->|"allocates seats"| node_db
node_localized -->|"takes screening"| node_assessment
node_assessment -->|"stores attempts"| node_db
node_localized -->|"tracks learning"| node_lms
node_lms -->|"records completion"| node_db
node_lms -.->|"qualifies for certificate"| node_certificates
node_certificates -->|"records certificate"| node_db
node_certificates -->|"stores document"| node_storage
node_localized -->|"requests document"| node_certdelivery
node_certdelivery -->|"checks access"| node_serverclient
node_serverclient -->|"reads certificate"| node_db
node_certdelivery -->|"mints signed URL"| node_storage
node_localized -->|"requests consultation"| node_consultations
node_consultations -->|"updates requests"| node_db
node_localized -->|"requests equipment"| node_requisitions
node_requisitions -->|"reserves stock"| node_db
node_requisitions -.->|"supports custody"| node_logistics
node_logistics -->|"records custody"| node_db
node_clearance -->|"checks preconditions"| node_db
node_lms -.->|"provides completion state"| node_clearance
node_staffroutes -->|"manages publication"| node_authoring
node_authoring -->|"writes transitions"| node_db
node_staffroutes -->|"triages requests"| node_consultations
node_staffroutes -->|"reviews requests"| node_requisitions
node_serverclient -->|"queries with RLS"| node_db

click node_localized "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/tree/main/src/app/%5Blocale%5D"
click node_routing "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/i18n/routing.ts"
click node_publiccontent "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/queries/public.ts"
click node_authpages "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/%5Blocale%5D/register/page.tsx"
click node_authactions "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/auth/actions.ts"
click node_callback "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/auth/callback/route.ts"
click node_applications "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/admissions/actions.ts"
click node_readiness "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/admissions/readiness-actions.ts"
click node_allocation "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/admissions/staff-actions.ts"
click node_assessment "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/assessment/actions.ts"
click node_lms "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/lms/actions.ts"
click node_certificates "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/certificates/issue-document.ts"
click node_certdelivery "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/api/certificates/%5Bid%5D/document/route.ts"
click node_consultations "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/consultations/actions.ts"
click node_requisitions "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/requisitions/actions.ts"
click node_logistics "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/logistics/actions.ts"
click node_clearance "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/clearance/actions.ts"
click node_authoring "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/authoring/actions.ts"
click node_staffroutes "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/%5Blocale%5D/staff/page.tsx"
click node_serverclient "https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/supabase/server.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_localized,node_routing,node_publiccontent,node_authpages toneBlue
class node_applications,node_readiness,node_allocation,node_assessment,node_lms,node_certificates,node_certdelivery,node_storage toneAmber
class node_consultations,node_requisitions,node_logistics,node_clearance,node_authoring,node_staffroutes toneMint
class node_authactions,node_callback,node_db,node_serverclient toneRose
class node_member,node_supaauth toneIndigo
```

## Components

### Bilingual experience

- [Localized app routes](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/tree/main/src/app/%5Blocale%5D): `src/app/[locale]`
- [Locale routing](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/i18n/routing.ts): `src/i18n/routing.ts`
- [Public discovery](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/queries/public.ts): `src/lib/queries/public.ts`
- [Registration and login](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/%5Blocale%5D/register/page.tsx): `src/app/[locale]/register/page.tsx`

### Admissions and learning

- [Application workflow](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/admissions/actions.ts): `src/lib/admissions/actions.ts`
- [Readiness scoring](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/admissions/readiness-actions.ts): `src/lib/admissions/readiness-actions.ts`
- [Offers and allocation](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/admissions/staff-actions.ts): `src/lib/admissions/staff-actions.ts`
- [Screening and grading](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/assessment/actions.ts): `src/lib/assessment/actions.ts`
- [Learning and attendance](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/lms/actions.ts): `src/lib/lms/actions.ts`
- [Certificate issuance](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/certificates/issue-document.ts): `src/lib/certificates/issue-document.ts`
- [Certificate delivery](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/api/certificates/%5Bid%5D/document/route.ts): `src/app/api/certificates/[id]/document/route.ts`

### Club operations

- [Consultations](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/consultations/actions.ts): `src/lib/consultations/actions.ts`
- [Hardware requisitions](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/requisitions/actions.ts): `src/lib/requisitions/actions.ts`
- [Custody and liabilities](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/logistics/actions.ts): `src/lib/logistics/actions.ts`
- [Completion clearance](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/clearance/actions.ts): `src/lib/clearance/actions.ts`
- [Editorial workflow](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/authoring/actions.ts): `src/lib/authoring/actions.ts`
- [Staff workspace](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/%5Blocale%5D/staff/page.tsx): `src/app/[locale]/staff/page.tsx`

### Identity and data

- [Authentication actions](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/auth/actions.ts): `src/lib/auth/actions.ts`
- [Email confirmation](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/app/auth/callback/route.ts): `src/app/auth/callback/route.ts`
- **PostgreSQL and RPC**
- [RLS-bound server client](https://github.com/malek-shammout/hamak-ai-robotics-club-platform/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`

### Other components

- **Member / visitor**
- **Supabase Auth**
- **Private certificate storage**

## Connections

- Member / visitor → Localized app routes: browses / submits
- Localized app routes → Locale routing: resolves locale
- Localized app routes → Public discovery: loads discovery
- Localized app routes → Registration and login: registers / signs in
- Registration and login → Authentication actions: invokes
- Authentication actions → Supabase Auth: authenticates
- Email confirmation → Supabase Auth: exchanges code
- Email confirmation → Localized app routes: redirects
- Localized app routes → Application workflow: submits application
- Application workflow → PostgreSQL and RPC: writes application
- Application workflow → Readiness scoring: requests scoring
- Readiness scoring → PostgreSQL and RPC: computes readiness
- Staff workspace → Offers and allocation: runs allocation
- Offers and allocation → PostgreSQL and RPC: allocates seats
- Localized app routes → Screening and grading: takes screening
- Screening and grading → PostgreSQL and RPC: stores attempts
- Localized app routes → Learning and attendance: tracks learning
- Learning and attendance → PostgreSQL and RPC: records completion
- Learning and attendance → Certificate issuance: qualifies for certificate
- Certificate issuance → PostgreSQL and RPC: records certificate
- Certificate issuance → Private certificate storage: stores document
- Localized app routes → Certificate delivery: requests document
- Certificate delivery → RLS-bound server client: checks access
- RLS-bound server client → PostgreSQL and RPC: reads certificate
- Certificate delivery → Private certificate storage: mints signed URL
- Localized app routes → Consultations: requests consultation
- Consultations → PostgreSQL and RPC: updates requests
- Localized app routes → Hardware requisitions: requests equipment
- Hardware requisitions → PostgreSQL and RPC: reserves stock
- Hardware requisitions → Custody and liabilities: supports custody
- Custody and liabilities → PostgreSQL and RPC: records custody
- Completion clearance → PostgreSQL and RPC: checks preconditions
- Learning and attendance → Completion clearance: provides completion state
- Staff workspace → Editorial workflow: manages publication
- Editorial workflow → PostgreSQL and RPC: writes transitions
- Staff workspace → Consultations: triages requests
- Staff workspace → Hardware requisitions: reviews requests
- RLS-bound server client → PostgreSQL and RPC: queries with RLS