# siimva/tulemuste-haldus architecture

> Architecture diagram of the GitHub repository siimva/tulemuste-haldus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siimva/tulemuste-haldus
- Repository: https://github.com/siimva/tulemuste-haldus

## Overview

Tulemuste haldus is a Next.js application for managing competitions, teams, registrations, scoring, and results. Organizers configure competitions and registration; teams apply or submit results; judges record element results; the application recalculates standings and exposes dashboards, leaderboards, and analysis. It also supports multi-competition series, notifications, and security auditing. The graph follows the sampled API and library references; unsampled capabilities are represented by their exact tree paths, but their internal call relationships are not asserted.

Main entry points: [`src/lib/prisma.ts`](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/prisma.ts) (PostgreSQL), [`src/lib/auth.ts`](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/auth.ts) (Sign-in), [`src/app/api/elements/[id]/results/route.ts`](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/elements/%5Bid%5D/results/route.ts) (Result entry), [`src/lib/security.server.ts`](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/security.server.ts) (Security logging and limits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_auth["Sign-in<br/>[auth.ts]"]
  node_access["Competition access"]
end

subgraph group_competition["Competition management"]
  node_competition_api["Competition APIs<br/>[route.ts]"]
  node_element_setup["Element configuration<br/>[route.ts]"]
end

subgraph group_registration["Registration workflow"]
  node_registration_settings["Registration settings<br/>[route.ts]"]
  node_registration_api["Registration intake<br/>[route.ts]"]
  node_applications["Application review<br/>[route.ts]"]
  node_registration_form["Registration forms"]
  node_representative_api["Representative teams<br/>[route.ts]"]
end

subgraph group_results["Scoring and results"]
  node_result_entry["Result entry<br/>[route.ts]"]
  node_scoring_rules["Scoring rules<br/>[index.ts]"]
  node_recompute["Recompute standings<br/>[recompute.ts]"]
end

subgraph group_publication["Dashboards and series"]
  node_leaderboard["Leaderboards"]
  node_dashboard["Statistics dashboard"]
  node_series["National series ranking<br/>[seriesRanking.ts]"]
end

subgraph group_operations["Notifications and security"]
  node_database[("PostgreSQL<br/>[prisma.ts]")]
  node_notifications["Notifications"]
  node_security_routes["API security wrapper"]
  node_security_service["Security logging and limits<br/>[security.server.ts]"]
  node_security_events["Security event API<br/>[route.ts]"]
end

node_organizer(("Organizer"))
node_team(("Team representative"))
node_judge(("Judge"))
node_email["Resend email"]

node_organizer -->|"signs in"| node_auth
node_team -.->|"signs in"| node_auth
node_judge -.->|"signs in"| node_auth
node_auth -->|"checks identity"| node_database
node_auth -->|"records login events"| node_security_service
node_organizer -.->|"manages competition"| node_competition_api
node_competition_api -->|"checks permissions"| node_access
node_competition_api -->|"reads and writes"| node_database
node_organizer -.->|"configures elements"| node_element_setup
node_element_setup -->|"checks permissions"| node_access
node_element_setup -->|"reads and writes"| node_database
node_organizer -.->|"sets registration rules"| node_registration_settings
node_registration_settings -->|"checks permissions"| node_access
node_registration_settings -->|"updates settings"| node_database
node_team -.->|"submits registration"| node_registration_api
node_registration_api -->|"uses form definitions"| node_registration_form
node_registration_api -->|"stores registration"| node_database
node_organizer -.->|"reviews application"| node_applications
node_applications -->|"updates application"| node_database
node_applications -->|"delivers pending notices"| node_notifications
node_team -.->|"manages team"| node_representative_api
node_representative_api -->|"reads and writes"| node_database
node_judge -.->|"records results"| node_result_entry
node_result_entry -->|"checks permissions"| node_access
node_result_entry -->|"stores results"| node_database
node_result_entry -->|"recalculates standings"| node_recompute
node_recompute -->|"uses calculators"| node_scoring_rules
node_recompute -->|"reads and writes"| node_database
node_leaderboard -.->|"reads standings"| node_database
node_dashboard -.->|"reads competition data"| node_database
node_series -.->|"reads series results"| node_database
node_notifications -->|"reads and writes"| node_database
node_notifications -->|"sends email"| node_email
node_security_routes -->|"loads session"| node_auth
node_security_routes -->|"limits and audits requests"| node_security_service
node_security_service -->|"stores events and limits"| node_database
node_security_events -->|"queries security events"| node_security_service

click node_auth "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/auth.ts"
click node_access "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/competitionAccess.ts"
click node_competition_api "https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/competitions/%5Bid%5D/route.ts"
click node_element_setup "https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/competitions/%5Bid%5D/elements/route.ts"
click node_registration_settings "https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/competitions/%5Bid%5D/registration-settings/route.ts"
click node_registration_api "https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/competitions/%5Bid%5D/registrations/route.ts"
click node_applications "https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/registration-applications/%5Bid%5D/route.ts"
click node_registration_form "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/registrationForm.ts"
click node_representative_api "https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/representative/teams/%5BteamId%5D/route.ts"
click node_result_entry "https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/elements/%5Bid%5D/results/route.ts"
click node_scoring_rules "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/calculators/index.ts"
click node_recompute "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/recompute.ts"
click node_leaderboard "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/publicLeaderboard.ts"
click node_dashboard "https://github.com/siimva/tulemuste-haldus/tree/main/src/lib/dashboard"
click node_series "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/seriesRanking.ts"
click node_database "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/prisma.ts"
click node_notifications "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/notifications.server.ts"
click node_security_routes "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/securityRoute.server.ts"
click node_security_service "https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/security.server.ts"
click node_security_events "https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/security-events/route.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_auth,node_access toneBlue
class node_competition_api,node_element_setup toneAmber
class node_registration_settings,node_registration_api,node_applications,node_registration_form,node_representative_api toneMint
class node_result_entry,node_scoring_rules,node_recompute toneRose
class node_leaderboard,node_dashboard,node_series,node_organizer,node_team,node_judge,node_email toneIndigo
class node_database,node_notifications,node_security_routes,node_security_service,node_security_events toneTeal
```

## Components

### Identity and access

- [Sign-in](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Competition access](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/competitionAccess.ts): `src/lib/competitionAccess.ts`

### Competition management

- [Competition APIs](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/competitions/%5Bid%5D/route.ts): `src/app/api/competitions/[id]/route.ts`
- [Element configuration](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/competitions/%5Bid%5D/elements/route.ts): `src/app/api/competitions/[id]/elements/route.ts`

### Registration workflow

- [Registration settings](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/competitions/%5Bid%5D/registration-settings/route.ts): `src/app/api/competitions/[id]/registration-settings/route.ts`
- [Registration intake](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/competitions/%5Bid%5D/registrations/route.ts): `src/app/api/competitions/[id]/registrations/route.ts`
- [Application review](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/registration-applications/%5Bid%5D/route.ts): `src/app/api/registration-applications/[id]/route.ts`
- [Registration forms](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/registrationForm.ts): `src/lib/registrationForm.ts`
- [Representative teams](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/representative/teams/%5BteamId%5D/route.ts): `src/app/api/representative/teams/[teamId]/route.ts`

### Scoring and results

- [Result entry](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/elements/%5Bid%5D/results/route.ts): `src/app/api/elements/[id]/results/route.ts`
- [Scoring rules](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/calculators/index.ts): `src/lib/calculators/index.ts`
- [Recompute standings](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/recompute.ts): `src/lib/recompute.ts`

### Dashboards and series

- [Leaderboards](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/publicLeaderboard.ts): `src/lib/publicLeaderboard.ts`
- [Statistics dashboard](https://github.com/siimva/tulemuste-haldus/tree/main/src/lib/dashboard): `src/lib/dashboard`
- [National series ranking](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/seriesRanking.ts): `src/lib/seriesRanking.ts`

### Notifications and security

- [PostgreSQL](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/prisma.ts): `src/lib/prisma.ts`
- [Notifications](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/notifications.server.ts): `src/lib/notifications.server.ts`
- [API security wrapper](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/securityRoute.server.ts): `src/lib/securityRoute.server.ts`
- [Security logging and limits](https://github.com/siimva/tulemuste-haldus/blob/main/src/lib/security.server.ts): `src/lib/security.server.ts`
- [Security event API](https://github.com/siimva/tulemuste-haldus/blob/main/src/app/api/security-events/route.ts): `src/app/api/security-events/route.ts`

### Other components

- **Organizer**
- **Team representative**
- **Judge**
- **Resend email**

## Connections

- Organizer → Sign-in: signs in (evidence: `src/lib/auth.ts`)
- Team representative → Sign-in: signs in
- Judge → Sign-in: signs in
- Sign-in → PostgreSQL: checks identity (evidence: `src/lib/auth.ts`)
- Sign-in → Security logging and limits: records login events (evidence: `src/lib/auth.ts`)
- Organizer → Competition APIs: manages competition
- Competition APIs → Competition access: checks permissions (evidence: `src/app/api/competitions/[id]/route.ts`)
- Competition APIs → PostgreSQL: reads and writes (evidence: `src/app/api/competitions/[id]/route.ts`)
- Organizer → Element configuration: configures elements
- Element configuration → Competition access: checks permissions (evidence: `src/app/api/competitions/[id]/elements/route.ts`)
- Element configuration → PostgreSQL: reads and writes (evidence: `src/app/api/competitions/[id]/elements/route.ts`)
- Organizer → Registration settings: sets registration rules
- Registration settings → Competition access: checks permissions (evidence: `src/app/api/competitions/[id]/registration-settings/route.ts`)
- Registration settings → PostgreSQL: updates settings (evidence: `src/app/api/competitions/[id]/registration-settings/route.ts`)
- Team representative → Registration intake: submits registration
- Registration intake → Registration forms: uses form definitions (evidence: `src/app/api/competitions/[id]/registrations/route.ts`)
- Registration intake → PostgreSQL: stores registration (evidence: `src/app/api/competitions/[id]/registrations/route.ts`)
- Organizer → Application review: reviews application
- Application review → PostgreSQL: updates application (evidence: `src/app/api/registration-applications/[id]/route.ts`)
- Application review → Notifications: delivers pending notices (evidence: `src/app/api/registration-applications/[id]/route.ts`)
- Team representative → Representative teams: manages team
- Representative teams → PostgreSQL: reads and writes (evidence: `src/app/api/representative/teams/[teamId]/route.ts`)
- Judge → Result entry: records results
- Result entry → Competition access: checks permissions (evidence: `src/app/api/elements/[id]/results/route.ts`)
- Result entry → PostgreSQL: stores results (evidence: `src/app/api/elements/[id]/results/route.ts`)
- Result entry → Recompute standings: recalculates standings (evidence: `src/app/api/elements/[id]/results/route.ts`)
- Recompute standings → Scoring rules: uses calculators (evidence: `src/lib/recompute.ts`)
- Recompute standings → PostgreSQL: reads and writes (evidence: `src/lib/recompute.ts`)
- Leaderboards → PostgreSQL: reads standings
- Statistics dashboard → PostgreSQL: reads competition data
- National series ranking → PostgreSQL: reads series results
- Notifications → PostgreSQL: reads and writes (evidence: `src/lib/notifications.server.ts`)
- Notifications → Resend email: sends email (evidence: `src/lib/notifications.server.ts`)
- API security wrapper → Sign-in: loads session (evidence: `src/lib/securityRoute.server.ts`)
- API security wrapper → Security logging and limits: limits and audits requests (evidence: `src/lib/securityRoute.server.ts`)
- Security logging and limits → PostgreSQL: stores events and limits (evidence: `src/lib/security.server.ts`)
- Security event API → Security logging and limits: queries security events (evidence: `src/app/api/security-events/route.ts`)
