# bondandmass/hackathon-platform architecture

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

- Interactive diagram: https://gitdiagram.com/bondandmass/hackathon-platform
- Repository: https://github.com/bondandmass/hackathon-platform

## Overview

Hackathon Platform provides team formation, project submission, and judging/leaderboard workflows through three FastAPI services. Participants authenticate with Cognito, form teams, then submit a project file; judges score submissions, and users can view rankings. Each service owns its PostgreSQL tables, while submissions also use S3. The graph follows the documented service calls and the sampled route implementations; unsampled service internals are represented only at supported directory paths.

Main entry points: [`submission-service/app/routes.py`](https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/routes.py) (Submission routes), [`judging-service/app/routes.py`](https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/routes.py) (Judging routes), [`team-service/app/routes.py`](https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/routes.py) (Team routes), [`team-service/app/core/db.py`](https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/core/db.py) (Team database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_teams["Team service"]
  node_team_api["Team routes<br/>[routes.py]"]
  node_team_runtime["Team runtime"]
  node_team_auth["Team auth<br/>[auth.py]"]
  node_team_models["Team records<br/>[models.py]"]
  node_team_db[("Team database<br/>[db.py]")]
end

subgraph group_submissions["Submission service"]
  node_submission_api["Submission routes<br/>[routes.py]"]
  node_submission_runtime["Submission runtime"]
  node_submission_auth["Submission auth<br/>[auth.py]"]
  node_submission_models["Submission records<br/>[models.py]"]
  node_submission_db[("Submission database<br/>[db.py]")]
  node_submission_storage["S3 file storage<br/>[storage.py]"]
end

subgraph group_judging["Judging service"]
  node_judging_api["Judging routes<br/>[routes.py]"]
  node_judging_runtime["Judging runtime"]
  node_judging_auth["Judging auth<br/>[auth.py]"]
  node_judging_models["Score records<br/>[models.py]"]
  node_judging_db[("Judging database<br/>[db.py]")]
  node_scoring["Scoring and ranking<br/>[scoring.py]"]
end

subgraph group_platform["Platform services"]
  node_cognito["Amazon Cognito"]
  node_postgres[("RDS PostgreSQL")]
  node_s3[("Amazon S3")]
end

node_user(("Platform user"))

node_user -->|"manages teams"| node_team_api
node_user -->|"uploads projects"| node_submission_api
node_user -->|"scores projects"| node_judging_api
node_team_api -->|"checks access"| node_team_auth
node_team_api -->|"reads and writes"| node_team_models
node_team_api -->|"uses sessions"| node_team_db
node_team_auth -->|"validates tokens"| node_cognito
node_team_models -->|"maps records"| node_team_db
node_submission_api -->|"checks access"| node_submission_auth
node_submission_api -->|"looks up team"| node_team_api
node_submission_api -->|"reads and writes"| node_submission_models
node_submission_api -->|"uses sessions"| node_submission_db
node_submission_api -->|"stores files"| node_submission_storage
node_submission_auth -->|"validates tokens"| node_cognito
node_submission_models -->|"maps records"| node_submission_db
node_submission_storage -->|"uploads and links"| node_s3
node_judging_api -->|"checks access"| node_judging_auth
node_judging_api -->|"checks submission"| node_submission_api
node_judging_api -->|"reads and writes"| node_judging_models
node_judging_api -->|"uses sessions"| node_judging_db
node_judging_api -->|"calculates rankings"| node_scoring
node_judging_auth -->|"validates tokens"| node_cognito
node_judging_models -->|"maps records"| node_judging_db
node_team_runtime -->|"initializes tables"| node_team_db
node_submission_runtime -->|"initializes tables"| node_submission_db
node_judging_runtime -->|"initializes tables"| node_judging_db
node_team_db -->|"connects to"| node_postgres
node_submission_db -->|"connects to"| node_postgres
node_judging_db -->|"connects to"| node_postgres

click node_team_api "https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/routes.py"
click node_team_runtime "https://github.com/bondandmass/hackathon-platform/tree/application-layer/team-service/app/core"
click node_team_auth "https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/core/auth.py"
click node_team_models "https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/models.py"
click node_team_db "https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/core/db.py"
click node_submission_api "https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/routes.py"
click node_submission_runtime "https://github.com/bondandmass/hackathon-platform/tree/application-layer/submission-service/app/core"
click node_submission_auth "https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/core/auth.py"
click node_submission_models "https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/models.py"
click node_submission_db "https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/core/db.py"
click node_submission_storage "https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/storage.py"
click node_judging_api "https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/routes.py"
click node_judging_runtime "https://github.com/bondandmass/hackathon-platform/tree/application-layer/judging-service/app/core"
click node_judging_auth "https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/core/auth.py"
click node_judging_models "https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/models.py"
click node_judging_db "https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/core/db.py"
click node_scoring "https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/scoring.py"

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_team_api,node_team_runtime,node_team_auth,node_team_models,node_team_db,node_user toneBlue
class node_submission_api,node_submission_runtime,node_submission_auth,node_submission_models,node_submission_db,node_submission_storage toneAmber
class node_judging_api,node_judging_runtime,node_judging_auth,node_judging_models,node_judging_db,node_scoring toneMint
class node_cognito,node_postgres,node_s3 toneRose
```

## Components

### Team service

- [Team routes](https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/routes.py): `team-service/app/routes.py`
- [Team runtime](https://github.com/bondandmass/hackathon-platform/tree/application-layer/team-service/app/core): `team-service/app/core`
- [Team auth](https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/core/auth.py): `team-service/app/core/auth.py`
- [Team records](https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/models.py): `team-service/app/models.py`
- [Team database](https://github.com/bondandmass/hackathon-platform/blob/application-layer/team-service/app/core/db.py): `team-service/app/core/db.py`

### Submission service

- [Submission routes](https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/routes.py): `submission-service/app/routes.py`
- [Submission runtime](https://github.com/bondandmass/hackathon-platform/tree/application-layer/submission-service/app/core): `submission-service/app/core`
- [Submission auth](https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/core/auth.py): `submission-service/app/core/auth.py`
- [Submission records](https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/models.py): `submission-service/app/models.py`
- [Submission database](https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/core/db.py): `submission-service/app/core/db.py`
- [S3 file storage](https://github.com/bondandmass/hackathon-platform/blob/application-layer/submission-service/app/storage.py): `submission-service/app/storage.py`

### Judging service

- [Judging routes](https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/routes.py): `judging-service/app/routes.py`
- [Judging runtime](https://github.com/bondandmass/hackathon-platform/tree/application-layer/judging-service/app/core): `judging-service/app/core`
- [Judging auth](https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/core/auth.py): `judging-service/app/core/auth.py`
- [Score records](https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/models.py): `judging-service/app/models.py`
- [Judging database](https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/core/db.py): `judging-service/app/core/db.py`
- [Scoring and ranking](https://github.com/bondandmass/hackathon-platform/blob/application-layer/judging-service/app/scoring.py): `judging-service/app/scoring.py`

### Platform services

- **Amazon Cognito**
- **RDS PostgreSQL**
- **Amazon S3**

### Other components

- **Platform user**

## Connections

- Platform user → Team routes: manages teams (evidence: `README.md`)
- Platform user → Submission routes: uploads projects (evidence: `README.md`)
- Platform user → Judging routes: scores projects (evidence: `README.md`)
- Team routes → Team auth: checks access (evidence: `team-service/app/routes.py`)
- Team routes → Team records: reads and writes (evidence: `team-service/app/routes.py`)
- Team routes → Team database: uses sessions (evidence: `team-service/app/routes.py`)
- Team auth → Amazon Cognito: validates tokens (evidence: `team-service/app/core/auth.py`)
- Team records → Team database: maps records (evidence: `team-service/app/models.py`)
- Submission routes → Submission auth: checks access (evidence: `submission-service/app/routes.py`)
- Submission routes → Team routes: looks up team (evidence: `submission-service/app/routes.py`)
- Submission routes → Submission records: reads and writes (evidence: `submission-service/app/routes.py`)
- Submission routes → Submission database: uses sessions (evidence: `submission-service/app/routes.py`)
- Submission routes → S3 file storage: stores files (evidence: `submission-service/app/routes.py`)
- Submission auth → Amazon Cognito: validates tokens (evidence: `submission-service/app/core/auth.py`)
- Submission records → Submission database: maps records (evidence: `submission-service/app/models.py`)
- S3 file storage → Amazon S3: uploads and links (evidence: `submission-service/app/storage.py`)
- Judging routes → Judging auth: checks access (evidence: `judging-service/app/routes.py`)
- Judging routes → Submission routes: checks submission (evidence: `judging-service/app/routes.py`)
- Judging routes → Score records: reads and writes (evidence: `judging-service/app/routes.py`)
- Judging routes → Judging database: uses sessions (evidence: `judging-service/app/routes.py`)
- Judging routes → Scoring and ranking: calculates rankings (evidence: `judging-service/app/routes.py`)
- Judging auth → Amazon Cognito: validates tokens (evidence: `judging-service/app/core/auth.py`)
- Score records → Judging database: maps records (evidence: `judging-service/app/models.py`)
- Team runtime → Team database: initializes tables (evidence: `team-service/app/core/factory.py`)
- Submission runtime → Submission database: initializes tables (evidence: `submission-service/app/core/factory.py`)
- Judging runtime → Judging database: initializes tables (evidence: `judging-service/app/core/factory.py`)
- Team database → RDS PostgreSQL: connects to (evidence: `team-service/app/core/db.py`)
- Submission database → RDS PostgreSQL: connects to (evidence: `submission-service/app/core/db.py`)
- Judging database → RDS PostgreSQL: connects to (evidence: `judging-service/app/core/db.py`)
