# darwinjacob-rgb/forgeeval-ai architecture

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

- Interactive diagram: https://gitdiagram.com/darwinjacob-rgb/forgeeval-ai
- Repository: https://github.com/darwinjacob-rgb/forgeeval-ai

## Overview

ForgeEval is a hackathon platform for participants to find problems, submit project repositories, and receive automated evaluation, with organizer and judge tools for managing problems, submissions, and results. The main participant flow runs from the frontend through the API to a submission controller, which starts security, runtime, and AI evaluation and persists results. The graph also shows core management and review capabilities. Some subsystem details are represented at directory level because their source was not excerpted; those links are limited to documented or indexed relationships.

Main entry points: [`server/src/routes`](https://github.com/darwinjacob-rgb/forgeeval-ai/tree/main/server/src/routes) (API routes), [`server/src/controllers/participant.controller.ts`](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/participant.controller.ts) (Participant operations), [`server/src/controllers/submission.controller.ts`](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/submission.controller.ts) (Submission management), [`server/src/config/database.ts`](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/config/database.ts) (Prisma database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_participant_views["Participant views"]
  node_organizer_views["Organizer and judge views"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and management"]
  node_api_app["API application<br/>[app.ts]"]
  node_api_routes["API routes"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_participant_ops["Participant operations"]
  node_problem_ops["Problem management"]
  node_submission_ops["Submission management"]
  node_hackathon_ops["Hackathon management"]
  node_team_ops["Team management<br/>[team.controller.ts]"]
  node_judge_ops["Judge evaluations"]
  node_leaderboard_ops["Leaderboard"]
  node_evaluation_ops["Evaluation operations"]
end

subgraph group_evaluation["Submission evaluation"]
  node_security["Security analysis"]
  node_runtime["Runtime tests<br/>[runtime.service.ts]"]
  node_ai_evaluation["AI evaluation"]
end

subgraph group_data["Persistence"]
  node_database[("Prisma database<br/>[database.ts]")]
end

node_participant(("Participant"))

node_participant -->|"uses"| node_webapp
node_webapp -->|"renders"| node_participant_views
node_webapp -->|"renders"| node_organizer_views
node_participant_views -->|"requests data"| node_api_client
node_api_client -.->|"calls API"| node_api_app
node_api_app -->|"mounts"| node_api_routes
node_api_routes -->|"routes requests"| node_participant_ops
node_api_routes -->|"routes requests"| node_problem_ops
node_api_routes -->|"routes requests"| node_submission_ops
node_api_routes -->|"protects routes"| node_auth
node_participant_ops -->|"reads and writes"| node_database
node_submission_ops -->|"reads and writes"| node_database
node_problem_ops -->|"reads and writes"| node_database
node_team_ops -->|"reads and writes"| node_database
node_submission_ops -->|"runs analysis"| node_security
node_submission_ops -->|"runs tests"| node_runtime
node_submission_ops -->|"evaluates submission"| node_ai_evaluation
node_participant_ops -->|"runs analysis"| node_security
node_participant_ops -->|"runs tests"| node_runtime
node_participant_ops -->|"evaluates submission"| node_ai_evaluation
node_evaluation_ops -->|"uses service"| node_security
node_evaluation_ops -->|"uses service"| node_runtime
node_evaluation_ops -->|"uses service"| node_ai_evaluation

click node_webapp "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/src/App.tsx"
click node_participant_views "https://github.com/darwinjacob-rgb/forgeeval-ai/tree/main/src/components/participant"
click node_organizer_views "https://github.com/darwinjacob-rgb/forgeeval-ai/tree/main/src/components"
click node_api_client "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/src/services/api.ts"
click node_api_app "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/app.ts"
click node_api_routes "https://github.com/darwinjacob-rgb/forgeeval-ai/tree/main/server/src/routes"
click node_auth "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/middleware/auth.ts"
click node_participant_ops "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/participant.controller.ts"
click node_problem_ops "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/problem.controller.ts"
click node_submission_ops "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/submission.controller.ts"
click node_hackathon_ops "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/hackathon.controller.ts"
click node_team_ops "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/team.controller.ts"
click node_judge_ops "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/judge.controller.ts"
click node_leaderboard_ops "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/leaderboard.controller.ts"
click node_evaluation_ops "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/evaluation.controller.ts"
click node_security "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/services/security.service.ts"
click node_runtime "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/services/runtime.service.ts"
click node_ai_evaluation "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/services/aiEvaluation.service.ts"
click node_database "https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/config/database.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_webapp,node_participant_views,node_organizer_views,node_api_client toneBlue
class node_api_app,node_api_routes,node_auth,node_participant_ops,node_problem_ops,node_submission_ops,node_hackathon_ops,node_team_ops,node_judge_ops,node_leaderboard_ops,node_evaluation_ops toneAmber
class node_security,node_runtime,node_ai_evaluation toneMint
class node_database toneRose
class node_participant toneIndigo
```

## Components

### Web application

- [Web app](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/src/App.tsx): `src/App.tsx`
- [Participant views](https://github.com/darwinjacob-rgb/forgeeval-ai/tree/main/src/components/participant): `src/components/participant`
- [Organizer and judge views](https://github.com/darwinjacob-rgb/forgeeval-ai/tree/main/src/components): `src/components`
- [API client](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/src/services/api.ts): `src/services/api.ts`

### API and management

- [API application](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/app.ts): `server/src/app.ts`
- [API routes](https://github.com/darwinjacob-rgb/forgeeval-ai/tree/main/server/src/routes): `server/src/routes`
- [Authentication](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/middleware/auth.ts): `server/src/middleware/auth.ts`
- [Participant operations](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/participant.controller.ts): `server/src/controllers/participant.controller.ts`
- [Problem management](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/problem.controller.ts): `server/src/controllers/problem.controller.ts`
- [Submission management](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/submission.controller.ts): `server/src/controllers/submission.controller.ts`
- [Hackathon management](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/hackathon.controller.ts): `server/src/controllers/hackathon.controller.ts`
- [Team management](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/team.controller.ts): `server/src/controllers/team.controller.ts`
- [Judge evaluations](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/judge.controller.ts): `server/src/controllers/judge.controller.ts`
- [Leaderboard](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/leaderboard.controller.ts): `server/src/controllers/leaderboard.controller.ts`
- [Evaluation operations](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/controllers/evaluation.controller.ts): `server/src/controllers/evaluation.controller.ts`

### Submission evaluation

- [Security analysis](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/services/security.service.ts): `server/src/services/security.service.ts`
- [Runtime tests](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/services/runtime.service.ts): `server/src/services/runtime.service.ts`
- [AI evaluation](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/services/aiEvaluation.service.ts): `server/src/services/aiEvaluation.service.ts`

### Persistence

- [Prisma database](https://github.com/darwinjacob-rgb/forgeeval-ai/blob/main/server/src/config/database.ts): `server/src/config/database.ts`

### Other components

- **Participant**

## Connections

- Participant → Web app: uses
- Web app → Participant views: renders (evidence: `src/App.tsx`)
- Web app → Organizer and judge views: renders (evidence: `src/App.tsx`)
- Participant views → API client: requests data (evidence: `src/components/participant/ParticipantDashboard.tsx`)
- API client → API application: calls API (evidence: `src/services/api.ts`)
- API application → API routes: mounts (evidence: `server/src/app.ts`)
- API routes → Participant operations: routes requests (evidence: `server/src/routes/participant.routes.ts`)
- API routes → Problem management: routes requests (evidence: `server/src/routes/problem.routes.ts`)
- API routes → Submission management: routes requests (evidence: `server/src/routes/index.ts`)
- API routes → Authentication: protects routes (evidence: `server/src/routes/participant.routes.ts`)
- Participant operations → Prisma database: reads and writes (evidence: `server/src/controllers/participant.controller.ts`)
- Submission management → Prisma database: reads and writes (evidence: `server/src/controllers/submission.controller.ts`)
- Problem management → Prisma database: reads and writes (evidence: `server/src/controllers/problem.controller.ts`)
- Team management → Prisma database: reads and writes (evidence: `server/src/controllers/team.controller.ts`)
- Submission management → Security analysis: runs analysis (evidence: `server/src/controllers/submission.controller.ts`)
- Submission management → Runtime tests: runs tests (evidence: `server/src/controllers/submission.controller.ts`)
- Submission management → AI evaluation: evaluates submission (evidence: `server/src/controllers/submission.controller.ts`)
- Participant operations → Security analysis: runs analysis (evidence: `server/src/controllers/participant.controller.ts`)
- Participant operations → Runtime tests: runs tests (evidence: `server/src/controllers/participant.controller.ts`)
- Participant operations → AI evaluation: evaluates submission (evidence: `server/src/controllers/participant.controller.ts`)
- Evaluation operations → Security analysis: uses service (evidence: `server/src/controllers/evaluation.controller.ts`)
- Evaluation operations → Runtime tests: uses service (evidence: `server/src/controllers/evaluation.controller.ts`)
- Evaluation operations → AI evaluation: uses service (evidence: `server/src/controllers/evaluation.controller.ts`)
