Choreo Planer API

Features

User authentication & JWT management
Soft-delete user accounts with recovery
Routine and element management (choreos, hits, lineups, positions)
Team collaboration tools
Club and season management
Notification system
Feedback collection
Contact form with email notifications
RESTful API with OpenAPI/Swagger documentation
AI-Powered MCP server for programmatic choreo management
Dockerized deployment with nginx load balancer and automatic updates via Watchtower

Quick Start

Prerequisites

This documentation provides quick start instructions for Docker because the server is designed to run in a Docker container.

Environment Setup

Rename each .env.template file to .env:
- .env.template → .env
- .server.env.template → .server.env
Fill in the required environment variables in each .env file. The .env files are located in the following directories:
- Root directory: .env (database config)
- Root directory: .server.env (server config)
- Optional: .backup.env (backup config)

Running the Server

Production

CODE

docker-compose up -d

The server will be available at the configured port by default.

Development

CODE

docker-compose -f docker-compose.yml -f dev.docker-compose.yml up -d

This starts Docker Compose with the development configuration which enables hot reloading.

Useful npm scripts

Script	Description
`npm run dev`	Start with nodemon for hot reload (TypeScript via tsx)
`npm run start`	Start the production build
`npm run build`	Lint and compile TypeScript
`npm run test`	Run all tests (lint + typecheck + unit)
`npm run test:unit`	Run Jest unit tests
`npm run lint`	Run ESLint
`npm run docs`	Generate JSDoc documentation
`npm run format`	Format code with Prettier

Project Structure

CODE

server/
├── src/
│   ├── db/
│   │   ├── models/          # Sequelize models
│   │   ├── migrations/      # Database migrations
│   │   ├── db.ts            # Database connection
│   │   ├── index.ts         # Model associations
│   │   ├── seed.json        # Seed data
│   │   └── seed.ts          # Database seeding
│   ├── i18n/                # Internationalization
│   │   ├── en.json5
│   │   └── de.json5
│   ├── mcp/                 # Model Context Protocol server
│   │   ├── resources/       # MCP resource definitions
│   │   ├── auth.ts          # MCP authentication
│   │   ├── helpers.ts       # MCP helper functions
│   │   ├── index.ts         # MCP entry point
│   │   └── tools.ts         # MCP tool definitions
│   ├── middlewares/          # Express middleware
│   │   ├── errorHandlingMiddleware.ts
│   │   ├── loggingMiddleware.ts
│   │   ├── rateLimitMiddleware.ts
│   │   ├── requestQueue.ts
│   │   └── validateMiddleware.ts
│   ├── plugins/             # Plugin configurations
│   │   ├── i18n.ts          # Internationalization setup
│   │   ├── nodemailer.ts    # Email setup
│   │   ├── passport.ts      # OAuth authentication
│   │   └── winston.ts       # Logging setup
│   ├── public/              # Static assets
│   ├── routes/              # API route handlers
│   │   ├── admin/           # Admin endpoints
│   │   ├── auth.ts
│   │   ├── choreo.ts
│   │   ├── club.ts
│   │   ├── contact.ts
│   │   ├── feedback.ts
│   │   ├── hit.ts
│   │   ├── lineup.ts
│   │   ├── member.ts
│   │   ├── notification.ts
│   │   ├── position.ts
│   │   ├── season.ts
│   │   ├── seasonTeam.ts
│   │   ├── team.ts
│   │   └── user.ts
│   ├── services/            # Business logic
│   ├── utils/               # Utility functions
│   ├── views/               # EJS templates
│   │   ├── admin/           # Admin dashboard
│   │   └── mail/            # Email templates
│   ├── docDefs.ts           # Swagger documentation definitions
│   └── index.ts             # Entry point
├── tests/
│   └── unit/                # Jest unit tests
├── loadbalancer/            # Nginx load balancer config
├── Dockerfile
├── dev.Dockerfile
├── arm32v7.Dockerfile
├── eslint.config.mjs
├── jest.config.ts
├── package.json
└── tsconfig.json

Architecture

CODE

graph
  User --IPv4/IPv6,https--> aws(AWS EC2 as Reverse Proxy)
  aws --IPv6,https--> Router

  BetterStack --IPv4/Ipv6,https--> aws

  subgraph On-Premise
    Router --> ReverseProxy
    subgraph HomeServer
      subgraph Docker
        ReverseProxy[Reverse Proxy] --> LoadBalancer
        LoadBalancer[Load Balancer] --> api
        sequelize --> db[(Postgres Database)]
        Unleash
        subgraph api[Choreo Planer API]
          sequelize
          i18n
          winston
          nodemailer
        end
      end
    end
  end

  nodemailer --https--> GoogleMail(Google Mail)
  mailProxy(DNS-provided E-Mail Proxy) --> GoogleMail
  GoogleMail --> Brevo(Brevo)

  githubactions --docker push--> dockerhub([Docker Hub])
  githubactions --trigger watchtower--> Watchtower[Watchtower]
  Watchtower --pull new image--> dockerhub

API Documentation

Once the server is running:

Swagger UI: /api-docs
JSDoc: /docs
Status: /status

Testing

CODE

npm run test

This runs ESLint and type checking first, then executes Jest unit tests.

Support

For questions or support, please open an issue or contact the maintainer via the website.