# ruthwik2/event-media-platform architecture

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

- Interactive diagram: https://gitdiagram.com/ruthwik2/event-media-platform
- Repository: https://github.com/ruthwik2/event-media-platform

## Overview

#### Purpose and Runtime Topology
A full-stack event-photography platform: events contain albums, albums contain photo/video media; users discover, share, moderate, and engage with content. It runs as a Next.js frontend, Express API/Socket.IO server, and PostgreSQL database, containerized together via `docker-compose.yml`. Core backend entry point: `backend/src/app.js`; frontend App Router root: `frontend/src/app/layout.tsx`.

#### Web Client and Navigation
The Next.js 14 client separates unauthenticated and protected experiences through route groups, with a shared main layout/navigation. Major workflows include gallery/search, media detail, uploads, event/album management, sharing, profiles, notifications, and admin approval queues.
Paths: `frontend/src/app/(auth)/layout.tsx`, `frontend/src/app/(main)/layout.tsx`, `frontend/src/app/(main)/events/[id]/page.tsx`.

#### API Composition and Authorization Boundary
Express mounts resource routers below `/api` for auth, events, albums, media, notifications, and club settings. Controllers implement resource workflows; JWT middleware authenticates requests and enforces role/access rules. Roles include admin, photographer, club member, and viewer, with additional private-content and collaborator/access-request controls.
Paths: `backend/src/app.js`, `backend/src/middleware/auth.js`, `backend/src/routes/mediaRoutes.js`.

#### Persistent Domain Model
Prisma/PostgreSQL is the source of truth for users, events, albums, media, social interactions, tags, notifications, access requests, and club settings. The central hierarchy is Event → Album → Media; media also connects to face metadata, AI labels/captions, moderation state, and user interactions. Schema migrations evolve approval, sharing, privacy, tag positioning, categories, and moderation.
Paths: `backend/prisma/schema.prisma`, `backend/prisma/migrations/20260602000000_add_access_requests/migration.sql`, `backend/prisma/seed.js`.

#### Media Ingestion and Delivery Pipeline
Bulk uploads enter through Multer middleware, then media controllers coordinate persistence and derived processing. `sharp` creates thumbnails/compressed output and composites SVG watermarks for downloads. Storage is a deployment boundary: local disk by default or AWS S3 when enabled. Media capabilities include search, favourites, tagging, comments, likes, download tracking, and visibility-aware delivery.
Paths: `backend/src/middleware/upload.js`, `backend/src/controllers/mediaController.js`, `backend/src/services/imageService.js`.

#### AWS Intelligence Pipeline
When S3/AWS are configured, uploaded images are analyzed through Rekognition for face indexing/search, labels, automatic captions, and content moderation. A user selfie establishes a Rekognition face identity; “My Photos” queries matching indexed media. Without S3/AWS credentials, this enrichment path is intentionally skipped rather than emulated.
Paths: `backend/src/services/rekognitionService.js`, `backend/src/services/s3Service.js`, `backend/src/config/aws.js`.

#### Sharing, Notifications, and Realtime
Events and albums expose guest-access paths via QR codes and share tokens, separate from authenticated API access. Tags, likes, comments, and approvals create notifications, delivered live through Socket.IO and represented in frontend Zustand state. The client establishes its realtime connection through a dedicated hook.
Paths: `backend/src/services/notificationService.js`, `backend/src/config/socket.js`, `frontend/src/hooks/useSocket.tsx`.

#### Deployment and External Dependencies
Docker orchestration provisions Postgres, backend, and frontend; backend configuration covers database, AWS, sockets, and logging. Browser API access is through the Axios client, while API CORS and Socket.IO depend on frontend/backend URLs. Material external services are PostgreSQL, optional AWS S3, and AWS Rekognition.
Paths: `docker-compose.yml`, `backend/src/config/database.js`, `frontend/src/lib/axios.ts`.

Main entry points: [`backend/prisma/schema.prisma`](https://github.com/ruthwik2/event-media-platform/blob/main/backend/prisma/schema.prisma) (Domain Database), [`backend/src/controllers/mediaController.js`](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/controllers/mediaController.js) (Media Workflow), [`backend/src/app.js`](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/app.js) (API Application), [`docker-compose.yml`](https://github.com/ruthwik2/event-media-platform/blob/main/docker-compose.yml) (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Next.js Client"]
  node_web_auth["Auth Routes<br/>Next.js route group<br/>[layout.tsx]"]
  node_web_main["Main App Routes<br/>Next.js route group<br/>[layout.tsx]"]
  node_event_gallery["Event Gallery<br/>Next.js page<br/>[page.tsx]"]
  node_axios["API Client<br/>Axios client<br/>[axios.ts]"]
  node_socket_hook["Realtime Hook<br/>Socket.IO client hook<br/>[useSocket.tsx]"]
end

subgraph group_api["Express API"]
  node_api_app["API Application<br/>Express / Socket.IO server<br/>[app.js]"]
  node_auth["JWT Access Control<br/>Express middleware<br/>[auth.js]"]
  node_media_routes["Media API<br/>Express router<br/>[mediaRoutes.js]"]
end

subgraph group_media["Media Pipeline"]
  node_upload["Upload Middleware<br/>Multer middleware<br/>[upload.js]"]
  node_media_controller["Media Workflow<br/>controller<br/>[mediaController.js]"]
  node_image_service["Image Processing<br/>Sharp service<br/>[imageService.js]"]
  node_storage[("Media Storage<br/>[s3Service.js]")]
end

subgraph group_data["Data &amp; Realtime"]
  node_notifications["Notification Service<br/>backend service"]
  node_socket_server["Socket Gateway<br/>Socket.IO configuration<br/>[socket.js]"]
  node_domain_db[("Domain Database<br/>Prisma / PostgreSQL<br/>[schema.prisma]")]
  node_seed["Database Seed<br/>Prisma seed<br/>[seed.js]"]
end

subgraph group_external["Infrastructure &amp; AWS"]
  node_compose{{"Docker Compose<br/>orchestration<br/>[docker-compose.yml]"}}
  node_rekognition{{"AWS Rekognition<br/>optional AI service"}}
  node_aws_config["AWS Configuration<br/>configuration boundary<br/>[aws.js]"]
  node_db_config["Database Configuration<br/>configuration boundary<br/>[database.js]"]
end

node_compose -->|"runs"| node_web_main
node_compose -->|"runs"| node_api_app
node_compose -->|"provisions"| node_domain_db
node_web_auth -->|"auth requests"| node_axios
node_web_main -->|"hosts"| node_event_gallery
node_web_main -->|"uses"| node_axios
node_axios -->|"HTTP /api"| node_api_app
node_socket_hook -->|"Socket.IO"| node_socket_server
node_api_app -->|"applies"| node_auth
node_api_app -->|"mounts"| node_media_routes
node_media_routes -->|"bulk upload"| node_upload
node_upload -->|"passes files"| node_media_controller
node_media_controller -->|"creates derivatives"| node_image_service
node_media_controller -->|"stores and serves"| node_storage
node_media_controller -->|"persists metadata"| node_domain_db
node_media_controller -.->|"optional enrichment"| node_rekognition
node_aws_config -.->|"enables S3"| node_storage
node_aws_config -.->|"enables"| node_rekognition
node_rekognition -->|"face and AI metadata"| node_domain_db
node_api_app -->|"engagement events"| node_notifications
node_notifications -->|"persists"| node_domain_db
node_notifications -->|"emits live updates"| node_socket_server
node_db_config -->|"connects"| node_domain_db
node_seed -->|"populates"| node_domain_db

click node_compose "https://github.com/ruthwik2/event-media-platform/blob/main/docker-compose.yml"
click node_web_auth "https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/app/(auth)/layout.tsx"
click node_web_main "https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/app/(main)/layout.tsx"
click node_event_gallery "https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/app/(main)/events/%5Bid%5D/page.tsx"
click node_axios "https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/lib/axios.ts"
click node_socket_hook "https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/hooks/useSocket.tsx"
click node_api_app "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/app.js"
click node_auth "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/middleware/auth.js"
click node_media_routes "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/routes/mediaRoutes.js"
click node_upload "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/middleware/upload.js"
click node_media_controller "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/controllers/mediaController.js"
click node_image_service "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/services/imageService.js"
click node_storage "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/services/s3Service.js"
click node_notifications "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/services/notificationService.js"
click node_socket_server "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/config/socket.js"
click node_domain_db "https://github.com/ruthwik2/event-media-platform/blob/main/backend/prisma/schema.prisma"
click node_seed "https://github.com/ruthwik2/event-media-platform/blob/main/backend/prisma/seed.js"
click node_rekognition "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/services/rekognitionService.js"
click node_aws_config "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/config/aws.js"
click node_db_config "https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/config/database.js"

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_web_auth,node_web_main,node_event_gallery,node_axios,node_socket_hook toneBlue
class node_api_app,node_auth,node_media_routes toneAmber
class node_upload,node_media_controller,node_image_service,node_storage toneMint
class node_notifications,node_socket_server,node_domain_db,node_seed toneRose
class node_compose,node_rekognition,node_aws_config,node_db_config toneIndigo
```

## Components

### Next.js Client

- [Auth Routes](https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/app/(auth)/layout.tsx): Next.js route group · Unauthenticated client experience. · `frontend/src/app/(auth)/layout.tsx`
- [Main App Routes](https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/app/(main)/layout.tsx): Next.js route group · Protected navigation and application shell. · `frontend/src/app/(main)/layout.tsx`
- [Event Gallery](https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/app/(main)/events/%5Bid%5D/page.tsx): Next.js page · `frontend/src/app/(main)/events/[id]/page.tsx`
- [API Client](https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/lib/axios.ts): Axios client · `frontend/src/lib/axios.ts`
- [Realtime Hook](https://github.com/ruthwik2/event-media-platform/blob/main/frontend/src/hooks/useSocket.tsx): Socket.IO client hook · Updates client notification state live. · `frontend/src/hooks/useSocket.tsx`

### Express API

- [API Application](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/app.js): Express / Socket.IO server · Mounts API routers and initializes realtime transport. · `backend/src/app.js`
- [JWT Access Control](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/middleware/auth.js): Express middleware · Authenticates users and enforces roles and private-content access. · `backend/src/middleware/auth.js`
- [Media API](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/routes/mediaRoutes.js): Express router · Media discovery, engagement, delivery, and upload endpoints. · `backend/src/routes/mediaRoutes.js`

### Media Pipeline

- [Upload Middleware](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/middleware/upload.js): Multer middleware · `backend/src/middleware/upload.js`
- [Media Workflow](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/controllers/mediaController.js): controller · Coordinates media persistence, visibility, and derived processing. · `backend/src/controllers/mediaController.js`
- [Image Processing](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/services/imageService.js): Sharp service · Creates derivatives and watermarked downloads. · `backend/src/services/imageService.js`
- [Media Storage](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/services/s3Service.js): local disk / S3 adapter · Uses local storage by default or S3 when configured. · `backend/src/services/s3Service.js`

### Data & Realtime

- [Notification Service](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/services/notificationService.js): backend service · Creates notifications from tags, engagement, and approvals. · `backend/src/services/notificationService.js`
- [Socket Gateway](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/config/socket.js): Socket.IO configuration · `backend/src/config/socket.js`
- [Domain Database](https://github.com/ruthwik2/event-media-platform/blob/main/backend/prisma/schema.prisma): Prisma / PostgreSQL · Source of truth for users, Event → Album → Media, interactions, access, and settings. · `backend/prisma/schema.prisma`
- [Database Seed](https://github.com/ruthwik2/event-media-platform/blob/main/backend/prisma/seed.js): Prisma seed · `backend/prisma/seed.js`

### Infrastructure & AWS

- [Docker Compose](https://github.com/ruthwik2/event-media-platform/blob/main/docker-compose.yml): orchestration · Runs frontend, backend, and Postgres together. · `docker-compose.yml`
- [AWS Rekognition](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/services/rekognitionService.js): optional AI service · Indexes faces and enriches images with labels, captions, and moderation. · `backend/src/services/rekognitionService.js`
- [AWS Configuration](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/config/aws.js): configuration boundary · Enables S3 and Rekognition only when credentials are configured. · `backend/src/config/aws.js`
- [Database Configuration](https://github.com/ruthwik2/event-media-platform/blob/main/backend/src/config/database.js): configuration boundary · `backend/src/config/database.js`

## Connections

- Docker Compose → Main App Routes: runs
- Docker Compose → API Application: runs
- Docker Compose → Domain Database: provisions
- Auth Routes → API Client: auth requests
- Main App Routes → Event Gallery: hosts
- Main App Routes → API Client: uses
- API Client → API Application: HTTP /api
- Realtime Hook → Socket Gateway: Socket.IO
- API Application → JWT Access Control: applies
- API Application → Media API: mounts
- Media API → Upload Middleware: bulk upload
- Upload Middleware → Media Workflow: passes files
- Media Workflow → Image Processing: creates derivatives
- Media Workflow → Media Storage: stores and serves
- Media Workflow → Domain Database: persists metadata
- Media Workflow → AWS Rekognition: optional enrichment
- AWS Configuration → Media Storage: enables S3
- AWS Configuration → AWS Rekognition: enables
- AWS Rekognition → Domain Database: face and AI metadata
- API Application → Notification Service: engagement events
- Notification Service → Domain Database: persists
- Notification Service → Socket Gateway: emits live updates
- Database Configuration → Domain Database: connects
- Database Seed → Domain Database: populates