# ampexqt/junta architecture

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

- Interactive diagram: https://gitdiagram.com/ampexqt/junta
- Repository: https://github.com/ampexqt/junta

## Overview

Junta is an environmental-event platform for participants, organizers, and administrators. The central workflow is event creation and moderation, followed by volunteer discovery and joining, event completion, ratings, and XP/organizer rewards. Its frontend provides map, calendar, participation, notification, KYC, and administration experiences; an Express API handles authentication, uploads, and event operations, with Firebase-backed state. The graph combines sampled imports and calls with explicitly documented README flows; some frontend-to-API and unsampled subsystem links are therefore documented or left unasserted.

Main entry points: [`server/routes/events.ts`](https://github.com/ampexqt/junta/blob/main/server/routes/events.ts) (Event API), [`src/App.tsx`](https://github.com/ampexqt/junta/blob/main/src/App.tsx) (Route application), [`server/routes/auth.ts`](https://github.com/ampexqt/junta/blob/main/server/routes/auth.ts) (Authentication and KYC API), [`server/index.ts`](https://github.com/ampexqt/junta/blob/main/server/index.ts) (Express API router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_app["Route application<br/>[App.tsx]"]
  node_authui["Registration and login<br/>[RegisterPage.tsx]"]
  node_authstate["Session and profile<br/>[AuthContext.tsx]"]
end

subgraph group_events["Event lifecycle"]
  node_discover["Event discovery<br/>[EventsPage.tsx]"]
  node_map["Live event map<br/>[MapViewPage.tsx]"]
  node_schedule["Event calendar<br/>[SchedulePage.tsx]"]
  node_create["Event creation"]
  node_organizer["Organizer management"]
  node_participation["Participation tracking"]
  node_ratings["Event and participant ratings<br/>[RateEventModal.tsx]"]
end

subgraph group_identity["Identity and trust"]
  node_admin["Event and user administration"]
  node_kycui["Identity review"]
end

subgraph group_platform["API and services"]
  node_api["Express API router<br/>[index.ts]"]
  node_authapi["Authentication and KYC API<br/>[auth.ts]"]
  node_eventapi["Event API<br/>[events.ts]"]
  node_uploadapi["Upload API<br/>[upload.ts]"]
  node_guard["JWT access control<br/>[auth.ts]"]
  node_rewards["XP and organizer rewards<br/>[gamification.ts]"]
  node_notifications["Notifications<br/>[notifications.ts]"]
end

subgraph group_state["Persistence and integrations"]
  node_firebase["Client Firebase services<br/>[firebase.ts]"]
  node_firestore[("Firebase Admin services<br/>[firebase-admin.ts]")]
  node_cloudinary["Image storage<br/>[cloudinary.ts]"]
  node_facepp["Face++ verification"]
  node_mail["Email delivery<br/>[mailer.ts]"]
end

node_visitor(("Platform users"))

node_visitor -->|"uses"| node_app
node_app -->|"routes to"| node_authui
node_app -->|"provides session"| node_authstate
node_app -->|"routes to"| node_discover
node_app -->|"routes to"| node_map
node_app -->|"routes to"| node_schedule
node_app -->|"routes to"| node_participation
node_app -->|"routes to"| node_admin
node_authui -.->|"registers through"| node_authapi
node_create -.->|"submits events"| node_eventapi
node_organizer -.->|"manages events"| node_eventapi
node_admin -.->|"approves events"| node_eventapi
node_discover -.->|"loads events"| node_eventapi
node_map -.->|"shows events"| node_eventapi
node_schedule -.->|"shows schedule"| node_eventapi
node_participation -.->|"joins events"| node_eventapi
node_ratings -.->|"submits ratings"| node_eventapi
node_kycui -.->|"reviews identity"| node_authapi
node_api -->|"mounts route"| node_authapi
node_api -->|"mounts route"| node_eventapi
node_api -->|"mounts route"| node_uploadapi
node_api -->|"protects endpoint"| node_guard
node_authapi -->|"sends email"| node_mail
node_authapi -->|"grants registration rewards"| node_rewards
node_authapi -.->|"uploads KYC images"| node_cloudinary
node_authapi -.->|"checks identity"| node_facepp
node_authapi -->|"persists profiles"| node_firestore
node_eventapi -->|"reads and writes"| node_firestore
node_eventapi -->|"awards event rewards"| node_rewards
node_eventapi -->|"creates alerts"| node_notifications
node_rewards -->|"updates reward state"| node_firestore
node_rewards -->|"notifies milestones"| node_notifications
node_authstate -->|"subscribes to profile"| node_firebase
node_visitor -.->|"stores profile images"| node_cloudinary

click node_app "https://github.com/ampexqt/junta/blob/main/src/App.tsx"
click node_authui "https://github.com/ampexqt/junta/blob/main/src/app/auth/RegisterPage.tsx"
click node_authstate "https://github.com/ampexqt/junta/blob/main/src/features/auth/AuthContext.tsx"
click node_discover "https://github.com/ampexqt/junta/blob/main/src/app/events/EventsPage.tsx"
click node_map "https://github.com/ampexqt/junta/blob/main/src/app/events/MapViewPage.tsx"
click node_schedule "https://github.com/ampexqt/junta/blob/main/src/app/events/SchedulePage.tsx"
click node_create "https://github.com/ampexqt/junta/blob/main/src/features/events/components/CreateEventModal.tsx"
click node_organizer "https://github.com/ampexqt/junta/blob/main/src/app/organizer/OrganizerMyEventsPage.tsx"
click node_participation "https://github.com/ampexqt/junta/blob/main/src/app/user/MyParticipationPage.tsx"
click node_ratings "https://github.com/ampexqt/junta/blob/main/src/features/events/components/RateEventModal.tsx"
click node_admin "https://github.com/ampexqt/junta/blob/main/src/app/admin/EventApprovalsPage.tsx"
click node_kycui "https://github.com/ampexqt/junta/blob/main/src/app/admin/UserVerificationPage.tsx"
click node_api "https://github.com/ampexqt/junta/blob/main/server/index.ts"
click node_authapi "https://github.com/ampexqt/junta/blob/main/server/routes/auth.ts"
click node_eventapi "https://github.com/ampexqt/junta/blob/main/server/routes/events.ts"
click node_uploadapi "https://github.com/ampexqt/junta/blob/main/server/routes/upload.ts"
click node_guard "https://github.com/ampexqt/junta/blob/main/server/middleware/auth.ts"
click node_rewards "https://github.com/ampexqt/junta/blob/main/server/services/gamification.ts"
click node_notifications "https://github.com/ampexqt/junta/blob/main/server/services/notifications.ts"
click node_firebase "https://github.com/ampexqt/junta/blob/main/src/lib/firebase.ts"
click node_firestore "https://github.com/ampexqt/junta/blob/main/server/config/firebase-admin.ts"
click node_cloudinary "https://github.com/ampexqt/junta/blob/main/server/config/cloudinary.ts"
click node_mail "https://github.com/ampexqt/junta/blob/main/server/config/mailer.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_app,node_authui,node_authstate,node_visitor toneBlue
class node_discover,node_map,node_schedule,node_create,node_organizer,node_participation,node_ratings toneAmber
class node_admin,node_kycui toneMint
class node_api,node_authapi,node_eventapi,node_uploadapi,node_guard,node_rewards,node_notifications toneRose
class node_firebase,node_firestore,node_cloudinary,node_facepp,node_mail toneIndigo
```

## Components

### Web application

- [Route application](https://github.com/ampexqt/junta/blob/main/src/App.tsx): `src/App.tsx`
- [Registration and login](https://github.com/ampexqt/junta/blob/main/src/app/auth/RegisterPage.tsx): `src/app/auth/RegisterPage.tsx`
- [Session and profile](https://github.com/ampexqt/junta/blob/main/src/features/auth/AuthContext.tsx): `src/features/auth/AuthContext.tsx`

### Event lifecycle

- [Event discovery](https://github.com/ampexqt/junta/blob/main/src/app/events/EventsPage.tsx): `src/app/events/EventsPage.tsx`
- [Live event map](https://github.com/ampexqt/junta/blob/main/src/app/events/MapViewPage.tsx): `src/app/events/MapViewPage.tsx`
- [Event calendar](https://github.com/ampexqt/junta/blob/main/src/app/events/SchedulePage.tsx): `src/app/events/SchedulePage.tsx`
- [Event creation](https://github.com/ampexqt/junta/blob/main/src/features/events/components/CreateEventModal.tsx): `src/features/events/components/CreateEventModal.tsx`
- [Organizer management](https://github.com/ampexqt/junta/blob/main/src/app/organizer/OrganizerMyEventsPage.tsx): `src/app/organizer/OrganizerMyEventsPage.tsx`
- [Participation tracking](https://github.com/ampexqt/junta/blob/main/src/app/user/MyParticipationPage.tsx): `src/app/user/MyParticipationPage.tsx`
- [Event and participant ratings](https://github.com/ampexqt/junta/blob/main/src/features/events/components/RateEventModal.tsx): `src/features/events/components/RateEventModal.tsx`

### Identity and trust

- [Event and user administration](https://github.com/ampexqt/junta/blob/main/src/app/admin/EventApprovalsPage.tsx): `src/app/admin/EventApprovalsPage.tsx`
- [Identity review](https://github.com/ampexqt/junta/blob/main/src/app/admin/UserVerificationPage.tsx): `src/app/admin/UserVerificationPage.tsx`

### API and services

- [Express API router](https://github.com/ampexqt/junta/blob/main/server/index.ts): `server/index.ts`
- [Authentication and KYC API](https://github.com/ampexqt/junta/blob/main/server/routes/auth.ts): `server/routes/auth.ts`
- [Event API](https://github.com/ampexqt/junta/blob/main/server/routes/events.ts): `server/routes/events.ts`
- [Upload API](https://github.com/ampexqt/junta/blob/main/server/routes/upload.ts): `server/routes/upload.ts`
- [JWT access control](https://github.com/ampexqt/junta/blob/main/server/middleware/auth.ts): `server/middleware/auth.ts`
- [XP and organizer rewards](https://github.com/ampexqt/junta/blob/main/server/services/gamification.ts): `server/services/gamification.ts`
- [Notifications](https://github.com/ampexqt/junta/blob/main/server/services/notifications.ts): `server/services/notifications.ts`

### Persistence and integrations

- [Client Firebase services](https://github.com/ampexqt/junta/blob/main/src/lib/firebase.ts): `src/lib/firebase.ts`
- [Firebase Admin services](https://github.com/ampexqt/junta/blob/main/server/config/firebase-admin.ts): `server/config/firebase-admin.ts`
- [Image storage](https://github.com/ampexqt/junta/blob/main/server/config/cloudinary.ts): `server/config/cloudinary.ts`
- **Face++ verification**
- [Email delivery](https://github.com/ampexqt/junta/blob/main/server/config/mailer.ts): `server/config/mailer.ts`

### Other components

- **Platform users**

## Connections

- Platform users → Route application: uses
- Route application → Registration and login: routes to (evidence: `src/App.tsx`)
- Route application → Session and profile: provides session (evidence: `src/App.tsx`)
- Route application → Event discovery: routes to (evidence: `src/App.tsx`)
- Route application → Live event map: routes to (evidence: `src/App.tsx`)
- Route application → Event calendar: routes to (evidence: `src/App.tsx`)
- Route application → Participation tracking: routes to (evidence: `src/App.tsx`)
- Route application → Event and user administration: routes to (evidence: `src/App.tsx`)
- Registration and login → Authentication and KYC API: registers through
- Event creation → Event API: submits events
- Organizer management → Event API: manages events
- Event and user administration → Event API: approves events
- Event discovery → Event API: loads events
- Live event map → Event API: shows events
- Event calendar → Event API: shows schedule
- Participation tracking → Event API: joins events
- Event and participant ratings → Event API: submits ratings
- Identity review → Authentication and KYC API: reviews identity
- Express API router → Authentication and KYC API: mounts route (evidence: `server/index.ts`)
- Express API router → Event API: mounts route (evidence: `server/index.ts`)
- Express API router → Upload API: mounts route (evidence: `server/index.ts`)
- Express API router → JWT access control: protects endpoint (evidence: `server/index.ts`)
- Authentication and KYC API → Email delivery: sends email (evidence: `server/routes/auth.ts`)
- Authentication and KYC API → XP and organizer rewards: grants registration rewards (evidence: `server/routes/auth.ts`)
- Authentication and KYC API → Image storage: uploads KYC images (evidence: `server/routes/auth.ts`)
- Authentication and KYC API → Face++ verification: checks identity (evidence: `server/routes/auth.ts`)
- Authentication and KYC API → Firebase Admin services: persists profiles (evidence: `server/routes/auth.ts`)
- Event API → Firebase Admin services: reads and writes (evidence: `server/routes/events.ts`)
- Event API → XP and organizer rewards: awards event rewards (evidence: `server/routes/events.ts`)
- Event API → Notifications: creates alerts (evidence: `server/routes/events.ts`)
- XP and organizer rewards → Firebase Admin services: updates reward state (evidence: `server/services/gamification.ts`)
- XP and organizer rewards → Notifications: notifies milestones (evidence: `server/services/gamification.ts`)
- Session and profile → Client Firebase services: subscribes to profile (evidence: `src/features/auth/AuthContext.tsx`)
- Platform users → Image storage: stores profile images