# devlup-labs/hacksprint architecture

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

- Interactive diagram: https://gitdiagram.com/devlup-labs/hacksprint
- Repository: https://github.com/devlup-labs/hacksprint

## Overview

HackSprint is a distributed hackathon platform: students discover events, register and build teams, submit projects or compete in on-spot matches, and view results; organizers configure events and judge submissions. The graph preserves the documented service boundaries and major product branches. README descriptions support several service and integration relationships; sampled source specifically confirms submission-review orchestration and notification dispatch, but does not expose every service’s internal wiring.

Main entry points: [`backend/api-gateway/src/index.js`](https://github.com/devlup-labs/hacksprint/blob/main/backend/api-gateway/src/index.js) (API gateway), [`backend/hackathon-service/src/routes/hackathon.routes.js`](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/routes/hackathon.routes.js) (Hackathon endpoints), [`backend/hackathon-service/src/services/submissionReviewService/submissionReview.service.js`](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/submissionReviewService/submissionReview.service.js) (Submission judging), [`backend/notification-service/src/services/notification.service.js`](https://github.com/devlup-labs/hacksprint/blob/main/backend/notification-service/src/services/notification.service.js) (Notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_frontend["React application<br/>[App.jsx]"]
  node_gateway["API gateway<br/>[index.js]"]
end

subgraph group_identity["Identity"]
  node_auth_routes["Auth endpoints<br/>[auth.routes.js]"]
  node_auth_service["Auth and profiles<br/>[auth.service.js]"]
end

subgraph group_events["Hackathon events"]
  node_hack_routes["Hackathon endpoints"]
  node_event_domain["Event lifecycle"]
  node_registration["Registration and teams"]
  node_submissions["Project submissions"]
  node_judging["Submission judging"]
  node_onspot["On-spot matches<br/>[match.service.js]"]
  node_results["Results and standings<br/>[result.service.js]"]
end

subgraph group_capabilities["Platform capabilities"]
  node_media["Media uploads<br/>[upload.service.js]"]
  node_chatbot["FAQ chatbot<br/>[gemini.service.js]"]
  node_notifications["Notifications"]
  node_notification_routes["Notification endpoints"]
  node_email_queue["Email and push queues<br/>[email.queue.js]"]
end

subgraph group_operations["Service infrastructure"]
  node_mongodb[("MongoDB")]
  node_redis[("Redis")]
  node_s3[("Amazon S3")]
end

node_browser(("Students and organizers"))
node_gemini_api["Gemini API"]
node_mail_push["Email and browser push"]

node_browser -->|"uses"| node_frontend
node_frontend -->|"API requests"| node_gateway
node_gateway -->|"proxies auth"| node_auth_routes
node_gateway -->|"proxies events"| node_hack_routes
node_gateway -->|"proxies notifications"| node_notification_routes
node_gateway -->|"proxies media"| node_media
node_gateway -->|"proxies chatbot"| node_chatbot
node_auth_routes -->|"dispatches"| node_auth_service
node_auth_service -->|"reads and writes"| node_mongodb
node_auth_service -->|"queues email"| node_email_queue
node_hack_routes -->|"dispatches"| node_event_domain
node_hack_routes -->|"dispatches"| node_registration
node_hack_routes -->|"dispatches"| node_submissions
node_hack_routes -->|"dispatches"| node_onspot
node_hack_routes -->|"dispatches"| node_results
node_judging -->|"reads and writes"| node_mongodb
node_judging -->|"updates scores"| node_results
node_judging -->|"dispatches alerts"| node_notifications
node_judging -->|"invalidates cache"| node_redis
node_event_domain -->|"reads and writes"| node_mongodb
node_registration -->|"reads and writes"| node_mongodb
node_submissions -->|"reads and writes"| node_mongodb
node_onspot -->|"reads and writes"| node_mongodb
node_results -->|"reads and writes"| node_mongodb
node_media -->|"stores files"| node_s3
node_chatbot -->|"queries"| node_gemini_api
node_notification_routes -->|"dispatches"| node_notifications
node_notifications -->|"stores notifications"| node_mongodb
node_notifications -->|"queues delivery"| node_email_queue
node_email_queue -->|"delivers asynchronously"| node_mail_push

click node_frontend "https://github.com/devlup-labs/hacksprint/blob/main/frontend/hack-sprint/src/App.jsx"
click node_gateway "https://github.com/devlup-labs/hacksprint/blob/main/backend/api-gateway/src/index.js"
click node_auth_routes "https://github.com/devlup-labs/hacksprint/blob/main/backend/auth-service/src/routes/auth.routes.js"
click node_auth_service "https://github.com/devlup-labs/hacksprint/blob/main/backend/auth-service/src/services/auth.service.js"
click node_hack_routes "https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/routes/hackathon.routes.js"
click node_event_domain "https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/hackathonService/hackathon.service.js"
click node_registration "https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/registrationService/registration.service.js"
click node_submissions "https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/submissionService/submission.service.js"
click node_judging "https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/submissionReviewService/submissionReview.service.js"
click node_onspot "https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/matchService/match.service.js"
click node_results "https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/resultService/result.service.js"
click node_media "https://github.com/devlup-labs/hacksprint/blob/main/backend/media-service/src/services/uploadService/upload.service.js"
click node_chatbot "https://github.com/devlup-labs/hacksprint/blob/main/backend/chatbot-service/src/services/gemini.service.js"
click node_notifications "https://github.com/devlup-labs/hacksprint/blob/main/backend/notification-service/src/services/notification.service.js"
click node_notification_routes "https://github.com/devlup-labs/hacksprint/blob/main/backend/notification-service/src/routes/notification.routes.js"
click node_email_queue "https://github.com/devlup-labs/hacksprint/blob/main/backend/notification-service/src/queues/email.queue.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_frontend,node_gateway,node_mail_push toneBlue
class node_auth_routes,node_auth_service toneAmber
class node_hack_routes,node_event_domain,node_registration,node_submissions,node_judging,node_onspot,node_results,node_gemini_api toneMint
class node_media,node_chatbot,node_notifications,node_notification_routes,node_email_queue toneRose
class node_mongodb,node_redis,node_s3,node_browser toneIndigo
```

## Components

### Web experience

- [React application](https://github.com/devlup-labs/hacksprint/blob/main/frontend/hack-sprint/src/App.jsx): `frontend/hack-sprint/src/App.jsx`
- [API gateway](https://github.com/devlup-labs/hacksprint/blob/main/backend/api-gateway/src/index.js): `backend/api-gateway/src/index.js`

### Identity

- [Auth endpoints](https://github.com/devlup-labs/hacksprint/blob/main/backend/auth-service/src/routes/auth.routes.js): `backend/auth-service/src/routes/auth.routes.js`
- [Auth and profiles](https://github.com/devlup-labs/hacksprint/blob/main/backend/auth-service/src/services/auth.service.js): `backend/auth-service/src/services/auth.service.js`

### Hackathon events

- [Hackathon endpoints](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/routes/hackathon.routes.js): `backend/hackathon-service/src/routes/hackathon.routes.js`
- [Event lifecycle](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/hackathonService/hackathon.service.js): `backend/hackathon-service/src/services/hackathonService/hackathon.service.js`
- [Registration and teams](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/registrationService/registration.service.js): `backend/hackathon-service/src/services/registrationService/registration.service.js`
- [Project submissions](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/submissionService/submission.service.js): `backend/hackathon-service/src/services/submissionService/submission.service.js`
- [Submission judging](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/submissionReviewService/submissionReview.service.js): `backend/hackathon-service/src/services/submissionReviewService/submissionReview.service.js`
- [On-spot matches](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/matchService/match.service.js): `backend/hackathon-service/src/services/matchService/match.service.js`
- [Results and standings](https://github.com/devlup-labs/hacksprint/blob/main/backend/hackathon-service/src/services/resultService/result.service.js): `backend/hackathon-service/src/services/resultService/result.service.js`

### Platform capabilities

- [Media uploads](https://github.com/devlup-labs/hacksprint/blob/main/backend/media-service/src/services/uploadService/upload.service.js): `backend/media-service/src/services/uploadService/upload.service.js`
- [FAQ chatbot](https://github.com/devlup-labs/hacksprint/blob/main/backend/chatbot-service/src/services/gemini.service.js): `backend/chatbot-service/src/services/gemini.service.js`
- [Notifications](https://github.com/devlup-labs/hacksprint/blob/main/backend/notification-service/src/services/notification.service.js): `backend/notification-service/src/services/notification.service.js`
- [Notification endpoints](https://github.com/devlup-labs/hacksprint/blob/main/backend/notification-service/src/routes/notification.routes.js): `backend/notification-service/src/routes/notification.routes.js`
- [Email and push queues](https://github.com/devlup-labs/hacksprint/blob/main/backend/notification-service/src/queues/email.queue.js): `backend/notification-service/src/queues/email.queue.js`

### Service infrastructure

- **MongoDB**
- **Redis**
- **Amazon S3**

### Other components

- **Students and organizers**
- **Gemini API**
- **Email and browser push**

## Connections

- Students and organizers → React application: uses
- React application → API gateway: API requests
- API gateway → Auth endpoints: proxies auth
- API gateway → Hackathon endpoints: proxies events
- API gateway → Notification endpoints: proxies notifications
- API gateway → Media uploads: proxies media
- API gateway → FAQ chatbot: proxies chatbot
- Auth endpoints → Auth and profiles: dispatches
- Auth and profiles → MongoDB: reads and writes
- Auth and profiles → Email and push queues: queues email
- Hackathon endpoints → Event lifecycle: dispatches
- Hackathon endpoints → Registration and teams: dispatches
- Hackathon endpoints → Project submissions: dispatches
- Hackathon endpoints → On-spot matches: dispatches
- Hackathon endpoints → Results and standings: dispatches
- Submission judging → MongoDB: reads and writes
- Submission judging → Results and standings: updates scores
- Submission judging → Notifications: dispatches alerts
- Submission judging → Redis: invalidates cache
- Event lifecycle → MongoDB: reads and writes
- Registration and teams → MongoDB: reads and writes
- Project submissions → MongoDB: reads and writes
- On-spot matches → MongoDB: reads and writes
- Results and standings → MongoDB: reads and writes
- Media uploads → Amazon S3: stores files
- FAQ chatbot → Gemini API: queries
- Notification endpoints → Notifications: dispatches
- Notifications → MongoDB: stores notifications
- Notifications → Email and push queues: queues delivery
- Email and push queues → Email and browser push: delivers asynchronously