# topcoder-platform/marathon-match-api-v6 architecture

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

- Interactive diagram: https://gitdiagram.com/topcoder-platform/marathon-match-api-v6
- Repository: https://github.com/topcoder-platform/marathon-match-api-v6

## Overview

This is a NestJS Marathon Match API that stores challenge scoring configuration, prepares tester JARs, accepts submission events, and launches ECS scoring work. The runtime workflow proceeds from configuration and tester setup through submission-triggered scoring, runner callbacks, and review-result handling; separate branches cover reruns, scheduled SYSTEM scoring, and runner-log retrieval. The tree and excerpts establish the API entry points and several service responsibilities, but do not show all worker, persistence, or ECS wiring, so uncertain links are omitted.

Main entry points: [`src/api/scoring-result/scoring-result.service.ts`](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/scoring-result.service.ts) (Scoring result service), [`src/shared/modules/global/prisma.service.ts`](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/global/prisma.service.ts) (Prisma access), [`src/main.ts`](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/main.ts) (HTTP API), [`src/api/tester/tester.service.ts`](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/tester.service.ts) (Tester service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Configuration and testers"]
  node_api["HTTP API<br/>[main.ts]"]
  node_config_controller["Config endpoints"]
  node_config_service["Config service"]
  node_tester_controller["Tester endpoints"]
  node_tester_service["Tester service<br/>[tester.service.ts]"]
  node_compile["Tester compilation"]
  node_compile_worker["Compilation worker"]
end

subgraph group_events["Submission intake"]
  node_kafka_consumer["Kafka consumer"]
  node_submission_handler["Submission handler"]
end

subgraph group_scoring["Scoring orchestration"]
  node_scoring_controller["Scoring endpoints"]
  node_scoring_service["Scoring result service"]
  node_system_scheduler["SYSTEM scheduler"]
  node_system_worker["SYSTEM worker"]
  node_relative_scheduler["Relative scheduler"]
  node_relative_worker["Relative worker"]
  node_timeout_scheduler["Test timeout scheduler"]
  node_timeout_worker["Test timeout worker"]
  node_email["Completion email"]
end

subgraph group_runtime["Runner and integrations"]
  node_ecs["ECS runner tasks"]
  node_ecs_service["ECS service<br/>[ecs.service.ts]"]
  node_runner["Marathon runner"]
  node_scorer["Scorer entry point<br/>[ScorerMain.java]"]
  node_submission_client["Submission client"]
  node_review_client["Review client<br/>[ReviewService.java]"]
  node_postgres[("PostgreSQL")]
  node_prisma["Prisma access<br/>[prisma.service.ts]"]
  node_logs_controller["Runner-log endpoint"]
  node_logs_service["Runner-log service"]
end

node_admin(("Administrator / caller"))
node_kafka["Kafka broker"]
node_submission_api["Submission API"]
node_cloudwatch[("CloudWatch logs")]

node_admin -->|"calls"| node_api
node_api -->|"routes"| node_config_controller
node_api -->|"routes"| node_tester_controller
node_api -->|"routes"| node_scoring_controller
node_config_controller -->|"calls"| node_config_service
node_tester_controller -->|"calls"| node_tester_service
node_tester_service -->|"compiles"| node_compile
node_compile -->|"dispatches"| node_compile_worker
node_config_service -->|"persists"| node_prisma
node_tester_service -->|"persists"| node_prisma
node_kafka -->|"delivers events"| node_kafka_consumer
node_kafka_consumer -->|"dispatches"| node_submission_handler
node_submission_handler -->|"requests scoring"| node_scoring_service
node_scoring_controller -->|"calls"| node_scoring_service
node_system_scheduler -->|"schedules"| node_system_worker
node_system_worker -->|"launches task"| node_ecs_service
node_scoring_service -->|"launches task"| node_ecs_service
node_ecs_service -->|"starts task"| node_ecs
node_ecs -->|"runs"| node_runner
node_runner -->|"executes scoring"| node_scorer
node_scorer -->|"fetches submission"| node_submission_client
node_submission_client -->|"reads metadata and files"| node_submission_api
node_scorer -->|"posts score"| node_review_client
node_review_client -->|"creates review"| node_submission_api
node_runner -->|"posts callback"| node_scoring_controller
node_scoring_service -->|"stores results"| node_prisma
node_relative_scheduler -->|"schedules"| node_relative_worker
node_relative_worker -->|"recomputes scores"| node_scoring_service
node_timeout_scheduler -->|"schedules"| node_timeout_worker
node_timeout_worker -->|"handles timeout"| node_scoring_service
node_scoring_service -.->|"notifies completion"| node_email
node_logs_controller -->|"calls"| node_logs_service
node_logs_service -->|"reads task mappings"| node_prisma
node_logs_service -->|"fetches events"| node_cloudwatch
node_prisma -->|"reads and writes"| node_postgres

click node_api "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/main.ts"
click node_config_controller "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/marathon-match-config/marathon-match-config.controller.ts"
click node_config_service "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/marathon-match-config/marathon-match-config.service.ts"
click node_tester_controller "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/tester.controller.ts"
click node_tester_service "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/tester.service.ts"
click node_compile "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/tester-compilation.service.ts"
click node_compile_worker "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/compilation-worker.service.ts"
click node_kafka_consumer "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/kafka/kafka-consumer.service.ts"
click node_submission_handler "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/kafka/handlers/marathon-match-submission.handler.ts"
click node_scoring_controller "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/scoring-result.controller.ts"
click node_scoring_service "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/scoring-result.service.ts"
click node_system_scheduler "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/system-score-dispatch-scheduler.service.ts"
click node_system_worker "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/system-score-dispatch-worker.service.ts"
click node_relative_scheduler "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/relative-scoring-recompute-scheduler.service.ts"
click node_relative_worker "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/relative-scoring-recompute-worker.service.ts"
click node_timeout_scheduler "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/system-test-timeout-scheduler.service.ts"
click node_timeout_worker "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/system-test-timeout-worker.service.ts"
click node_ecs_service "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/global/ecs.service.ts"
click node_runner "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/ecs-runner/boilerplate/src/main/java/com/topcoder/marathon/MarathonController.java"
click node_scorer "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/java/boilerplate/src/main/java/com/topcoder/scorer/ScorerMain.java"
click node_submission_client "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/java/boilerplate/src/main/java/com/topcoder/scorer/services/SubmissionService.java"
click node_review_client "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/java/boilerplate/src/main/java/com/topcoder/scorer/services/ReviewService.java"
click node_prisma "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/global/prisma.service.ts"
click node_logs_controller "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/submission-runner-log/submission-runner-log.controller.ts"
click node_logs_service "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/submission-runner-log/submission-runner-log.service.ts"
click node_email "https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/scoring-completion-email.service.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_api,node_config_controller,node_config_service,node_tester_controller,node_tester_service,node_compile,node_compile_worker toneBlue
class node_kafka_consumer,node_submission_handler,node_cloudwatch toneAmber
class node_scoring_controller,node_scoring_service,node_system_scheduler,node_system_worker,node_relative_scheduler,node_relative_worker,node_timeout_scheduler,node_timeout_worker,node_email,node_submission_api toneMint
class node_ecs,node_ecs_service,node_runner,node_scorer,node_submission_client,node_review_client,node_postgres,node_prisma,node_logs_controller,node_logs_service toneRose
class node_admin,node_kafka toneIndigo
```

## Components

### Configuration and testers

- [HTTP API](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/main.ts): `src/main.ts`
- [Config endpoints](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/marathon-match-config/marathon-match-config.controller.ts): `src/api/marathon-match-config/marathon-match-config.controller.ts`
- [Config service](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/marathon-match-config/marathon-match-config.service.ts): `src/api/marathon-match-config/marathon-match-config.service.ts`
- [Tester endpoints](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/tester.controller.ts): `src/api/tester/tester.controller.ts`
- [Tester service](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/tester.service.ts): `src/api/tester/tester.service.ts`
- [Tester compilation](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/tester-compilation.service.ts): `src/api/tester/tester-compilation.service.ts`
- [Compilation worker](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/tester/compilation-worker.service.ts): `src/api/tester/compilation-worker.service.ts`

### Submission intake

- [Kafka consumer](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/kafka/kafka-consumer.service.ts): `src/shared/modules/kafka/kafka-consumer.service.ts`
- [Submission handler](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/kafka/handlers/marathon-match-submission.handler.ts): `src/shared/modules/kafka/handlers/marathon-match-submission.handler.ts`

### Scoring orchestration

- [Scoring endpoints](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/scoring-result.controller.ts): `src/api/scoring-result/scoring-result.controller.ts`
- [Scoring result service](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/scoring-result.service.ts): `src/api/scoring-result/scoring-result.service.ts`
- [SYSTEM scheduler](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/system-score-dispatch-scheduler.service.ts): `src/api/scoring-result/system-score-dispatch-scheduler.service.ts`
- [SYSTEM worker](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/system-score-dispatch-worker.service.ts): `src/api/scoring-result/system-score-dispatch-worker.service.ts`
- [Relative scheduler](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/relative-scoring-recompute-scheduler.service.ts): `src/api/scoring-result/relative-scoring-recompute-scheduler.service.ts`
- [Relative worker](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/relative-scoring-recompute-worker.service.ts): `src/api/scoring-result/relative-scoring-recompute-worker.service.ts`
- [Test timeout scheduler](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/system-test-timeout-scheduler.service.ts): `src/api/scoring-result/system-test-timeout-scheduler.service.ts`
- [Test timeout worker](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/system-test-timeout-worker.service.ts): `src/api/scoring-result/system-test-timeout-worker.service.ts`
- [Completion email](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/scoring-result/scoring-completion-email.service.ts): `src/api/scoring-result/scoring-completion-email.service.ts`

### Runner and integrations

- **ECS runner tasks**
- [ECS service](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/global/ecs.service.ts): `src/shared/modules/global/ecs.service.ts`
- [Marathon runner](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/ecs-runner/boilerplate/src/main/java/com/topcoder/marathon/MarathonController.java): `ecs-runner/boilerplate/src/main/java/com/topcoder/marathon/MarathonController.java`
- [Scorer entry point](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/java/boilerplate/src/main/java/com/topcoder/scorer/ScorerMain.java): `src/java/boilerplate/src/main/java/com/topcoder/scorer/ScorerMain.java`
- [Submission client](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/java/boilerplate/src/main/java/com/topcoder/scorer/services/SubmissionService.java): `src/java/boilerplate/src/main/java/com/topcoder/scorer/services/SubmissionService.java`
- [Review client](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/java/boilerplate/src/main/java/com/topcoder/scorer/services/ReviewService.java): `src/java/boilerplate/src/main/java/com/topcoder/scorer/services/ReviewService.java`
- **PostgreSQL**
- [Prisma access](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/shared/modules/global/prisma.service.ts): `src/shared/modules/global/prisma.service.ts`
- [Runner-log endpoint](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/submission-runner-log/submission-runner-log.controller.ts): `src/api/submission-runner-log/submission-runner-log.controller.ts`
- [Runner-log service](https://github.com/topcoder-platform/marathon-match-api-v6/blob/develop/src/api/submission-runner-log/submission-runner-log.service.ts): `src/api/submission-runner-log/submission-runner-log.service.ts`

### Other components

- **Administrator / caller**
- **Kafka broker**
- **Submission API**
- **CloudWatch logs**

## Connections

- Administrator / caller → HTTP API: calls
- HTTP API → Config endpoints: routes
- HTTP API → Tester endpoints: routes
- HTTP API → Scoring endpoints: routes
- Config endpoints → Config service: calls
- Tester endpoints → Tester service: calls
- Tester service → Tester compilation: compiles
- Tester compilation → Compilation worker: dispatches
- Config service → Prisma access: persists
- Tester service → Prisma access: persists
- Kafka broker → Kafka consumer: delivers events
- Kafka consumer → Submission handler: dispatches
- Submission handler → Scoring result service: requests scoring
- Scoring endpoints → Scoring result service: calls
- SYSTEM scheduler → SYSTEM worker: schedules
- SYSTEM worker → ECS service: launches task
- Scoring result service → ECS service: launches task
- ECS service → ECS runner tasks: starts task
- ECS runner tasks → Marathon runner: runs
- Marathon runner → Scorer entry point: executes scoring
- Scorer entry point → Submission client: fetches submission
- Submission client → Submission API: reads metadata and files
- Scorer entry point → Review client: posts score
- Review client → Submission API: creates review
- Marathon runner → Scoring endpoints: posts callback
- Scoring result service → Prisma access: stores results
- Relative scheduler → Relative worker: schedules
- Relative worker → Scoring result service: recomputes scores
- Test timeout scheduler → Test timeout worker: schedules
- Test timeout worker → Scoring result service: handles timeout
- Scoring result service → Completion email: notifies completion
- Runner-log endpoint → Runner-log service: calls
- Runner-log service → Prisma access: reads task mappings
- Runner-log service → CloudWatch logs: fetches events
- Prisma access → PostgreSQL: reads and writes