# andreasnicklaus/cheer-choreo-tool architecture

> Architecture diagram of the GitHub repository andreasnicklaus/cheer-choreo-tool, 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/andreasnicklaus/cheer-choreo-tool
- Repository: https://github.com/andreasnicklaus/cheer-choreo-tool

## Overview

Choreo Planer is a web application for planning cheerleading and dance choreography. Coaches use the Vue interface to manage choreographies, counts, hits, lineups, and member positions, then export plans as PDFs or videos. The backend provides HTTP APIs, authentication and access sharing, domain services, persistence, and an MCP interface for programmatic choreo management. The README documents the product capabilities; sampled code confirms selected frontend routing and backend service/model relationships. Several domain routes and integrations are unsampled, so their links are shown as unverified where needed.

Main entry points: [`server/src/index.ts`](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/index.ts) (HTTP API server), [`server/src/services/ChoreoService.ts`](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/ChoreoService.ts) (Choreo services), [`server/src/services/UserService.ts`](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/UserService.ts) (User services), [`app/src/router/unlocalized-routes.mjs`](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/router/unlocalized-routes.mjs) (Page routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webapp["Vue application<br/>[App.vue]"]
  node_routes["Page routing"]
  node_client["API request client<br/>[RequestService.ts]"]
end

subgraph group_planning["Planning and exports"]
  node_editor["Choreo editor<br/>[EditView.vue]"]
  node_rosters["Teams and seasons<br/>[TeamView.vue]"]
  node_exports["PDF and video<br/>[VideoView.vue]"]
end

subgraph group_api["API and identity"]
  node_server["HTTP API server<br/>[index.ts]"]
  node_auth["Authentication<br/>[AuthService.ts]"]
end

subgraph group_domain["Domain services"]
  node_choreo["Choreo services<br/>[ChoreoService.ts]"]
  node_lineups["Lineup services<br/>[LineupService.ts]"]
  node_positions["Position services<br/>[PositionService.ts]"]
  node_users["User services<br/>[UserService.ts]"]
  node_access["Access control<br/>[accessControl.ts]"]
  node_records[("Planning records<br/>[choreo.ts]")]
  node_lineuprecords[("Lineup records<br/>[lineup.ts]")]
  node_memberrecords[("Member records<br/>[member.ts]")]
  node_userrecords[("User records<br/>[user.ts]")]
end

subgraph group_support["Integrations"]
  node_mcp["MCP tools<br/>[tools.ts]"]
  node_mail["Email delivery<br/>[MailService.ts]"]
  node_notifications["Notifications"]
end

node_coach(("Coach"))
node_emailservice["Email service"]
node_aiagent(("AI agent"))

node_coach -->|"uses"| node_webapp
node_webapp -.->|"renders routes"| node_routes
node_routes -->|"routes to"| node_editor
node_routes -->|"routes to"| node_rosters
node_routes -->|"routes to"| node_exports
node_editor -.->|"requests data"| node_client
node_rosters -.->|"requests data"| node_client
node_exports -.->|"requests data"| node_client
node_client -.->|"sends API requests"| node_server
node_server -.->|"registers routes"| node_auth
node_server -.->|"dispatches requests"| node_choreo
node_server -.->|"dispatches requests"| node_lineups
node_server -.->|"dispatches requests"| node_positions
node_server -.->|"dispatches requests"| node_users
node_auth -->|"uses"| node_users
node_choreo -->|"checks access"| node_access
node_choreo -->|"queries and updates"| node_records
node_choreo -.->|"uses"| node_lineups
node_lineups -->|"queries records"| node_lineuprecords
node_positions -->|"loads lineups"| node_lineuprecords
node_positions -->|"loads members"| node_memberrecords
node_positions -->|"checks access"| node_access
node_users -->|"queries records"| node_userrecords
node_users -->|"sends mail"| node_mail
node_users -->|"creates notifications"| node_notifications
node_mail -.->|"delivers email"| node_emailservice
node_aiagent -->|"uses MCP"| node_mcp
node_mcp -.->|"manages choreos"| node_choreo

click node_webapp "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/App.vue"
click node_routes "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/router/unlocalized-routes.mjs"
click node_editor "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/views/EditView.vue"
click node_rosters "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/views/TeamView.vue"
click node_exports "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/views/VideoView.vue"
click node_client "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/services/RequestService.ts"
click node_server "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/index.ts"
click node_auth "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/AuthService.ts"
click node_choreo "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/ChoreoService.ts"
click node_lineups "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/LineupService.ts"
click node_positions "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/PositionService.ts"
click node_users "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/UserService.ts"
click node_access "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/utils/accessControl.ts"
click node_records "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/db/models/choreo.ts"
click node_lineuprecords "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/db/models/lineup.ts"
click node_memberrecords "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/db/models/member.ts"
click node_userrecords "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/db/models/user.ts"
click node_mcp "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/mcp/tools.ts"
click node_mail "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/MailService.ts"
click node_notifications "https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/NotificationService.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_routes,node_client toneBlue
class node_editor,node_rosters,node_exports toneAmber
class node_server,node_auth toneMint
class node_choreo,node_lineups,node_positions,node_users,node_access,node_records,node_lineuprecords,node_memberrecords,node_userrecords toneRose
class node_mcp,node_mail,node_notifications,node_coach,node_emailservice,node_aiagent toneIndigo
```

## Components

### Web application

- [Vue application](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/App.vue): `app/src/App.vue`
- [Page routing](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/router/unlocalized-routes.mjs): `app/src/router/unlocalized-routes.mjs`
- [API request client](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/services/RequestService.ts): `app/src/services/RequestService.ts`

### Planning and exports

- [Choreo editor](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/views/EditView.vue): `app/src/views/EditView.vue`
- [Teams and seasons](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/views/TeamView.vue): `app/src/views/TeamView.vue`
- [PDF and video](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/app/src/views/VideoView.vue): `app/src/views/VideoView.vue`

### API and identity

- [HTTP API server](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/index.ts): `server/src/index.ts`
- [Authentication](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/AuthService.ts): `server/src/services/AuthService.ts`

### Domain services

- [Choreo services](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/ChoreoService.ts): `server/src/services/ChoreoService.ts`
- [Lineup services](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/LineupService.ts): `server/src/services/LineupService.ts`
- [Position services](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/PositionService.ts): `server/src/services/PositionService.ts`
- [User services](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/UserService.ts): `server/src/services/UserService.ts`
- [Access control](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/utils/accessControl.ts): `server/src/utils/accessControl.ts`
- [Planning records](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/db/models/choreo.ts): `server/src/db/models/choreo.ts`
- [Lineup records](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/db/models/lineup.ts): `server/src/db/models/lineup.ts`
- [Member records](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/db/models/member.ts): `server/src/db/models/member.ts`
- [User records](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/db/models/user.ts): `server/src/db/models/user.ts`

### Integrations

- [MCP tools](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/mcp/tools.ts): `server/src/mcp/tools.ts`
- [Email delivery](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/MailService.ts): `server/src/services/MailService.ts`
- [Notifications](https://github.com/andreasnicklaus/cheer-choreo-tool/blob/main/server/src/services/NotificationService.ts): `server/src/services/NotificationService.ts`

### Other components

- **Coach**
- **Email service**
- **AI agent**

## Connections

- Coach → Vue application: uses
- Vue application → Page routing: renders routes
- Page routing → Choreo editor: routes to (evidence: `app/src/router/unlocalized-routes.mjs`)
- Page routing → Teams and seasons: routes to (evidence: `app/src/router/unlocalized-routes.mjs`)
- Page routing → PDF and video: routes to (evidence: `app/src/router/unlocalized-routes.mjs`)
- Choreo editor → API request client: requests data
- Teams and seasons → API request client: requests data
- PDF and video → API request client: requests data
- API request client → HTTP API server: sends API requests
- HTTP API server → Authentication: registers routes
- HTTP API server → Choreo services: dispatches requests
- HTTP API server → Lineup services: dispatches requests
- HTTP API server → Position services: dispatches requests
- HTTP API server → User services: dispatches requests
- Authentication → User services: uses (evidence: `server/src/services/AuthService.ts`)
- Choreo services → Access control: checks access (evidence: `server/src/services/ChoreoService.ts`)
- Choreo services → Planning records: queries and updates (evidence: `server/src/services/ChoreoService.ts`)
- Choreo services → Lineup services: uses (evidence: `server/src/services/ChoreoService.ts`)
- Lineup services → Lineup records: queries records (evidence: `server/src/services/LineupService.ts`)
- Position services → Lineup records: loads lineups (evidence: `server/src/services/PositionService.ts`)
- Position services → Member records: loads members (evidence: `server/src/services/PositionService.ts`)
- Position services → Access control: checks access (evidence: `server/src/services/PositionService.ts`)
- User services → User records: queries records (evidence: `server/src/services/UserService.ts`)
- User services → Email delivery: sends mail (evidence: `server/src/services/UserService.ts`)
- User services → Notifications: creates notifications (evidence: `server/src/services/UserService.ts`)
- Email delivery → Email service: delivers email
- AI agent → MCP tools: uses MCP
- MCP tools → Choreo services: manages choreos
