Skip to content

PlayTelly CoreAPI

CoreAPI is the central backend service for the PlayTelly platform — a multi-tenant streaming infrastructure system. It handles channel management, media, provisioning, spatial organization, and integrates with external services like Castis Streamer nodes.

Architecture Overview

graph LR
    Frontend["PlayoutAdmin (React)"] --> CoreAPI
    CoreAPI --> PostgreSQL
    CoreAPI --> StreamerNodes["Castis Streamer Nodes"]
    CoreAPI --> SeaweedFS["SeaweedFS (Object Storage)"]
    CoreAPI --> Zitadel["Zitadel (Auth)"]

CoreAPI is a Go Fiber server organized by domain packages. Each domain is independently developed and owns its own models, handlers, routes, and validation.

Domain Structure

Each domain lives under domain/ and follows a consistent file layout:

File Purpose
models.go GORM models and DB types
handler.go Request handlers (business logic)
routes.go Route registration
validation.go Input validation helpers
helper.go Domain-specific utilities

Current domains:

Domain Responsibility
service Streamer node registry and health
playback Channel and origin management
media Media uploads, processing, storage
spatial Locations, venues, zones, endpoints
provisioning Device management
tenant Organizations and workspaces
catalogue Playlists and media channels
advertising Campaign scheduling
identity User and role management

Shared packages live under pkg/:

  • pkg/db — database connection and migrations
  • pkg/response — standard response envelope (success/data/meta)
  • pkg/StreamerClient — HTTP client for Castis Streamer API
  • pkg/storage — SeaweedFS/S3 client
  • pkg/seed — development seed data

Getting Started

Prerequisites

  • Docker Desktop running
  • Git access to the Castis GitLab

1. Set up your root folder

mkdir Roots && cd Roots

2. Clone required repositories

git clone https://mashup.castis.io/playtelly/Quickstart.git
git clone https://mashup.castis.io/playtelly/CoreAPI.git
git clone https://mashup.castis.io/playtelly/AdminApp/PlayoutAdmin.git
git clone https://mashup.castis.io/playtelly/documentation.git

All four repos required for make noauths

noauths builds CoreAPI, PlayoutAdmin, and the Documentation site together. If any repo is missing from the same root folder, Docker Compose will fail to find the build context and exit with an error.

Your root folder should look like this before running any make command:

Roots/
├── Quickstart/
├── CoreAPI/
├── PlayoutAdmin/
└── documentation/

3. Start the stack

cd Quickstart
make noauths

Frontend apps use Nginx

Some frontend services (e.g. PlayoutAdmin) use Nginx inside Docker. If the backend service they proxy to isn't running, the container will fail to start. Always check which services a make target includes before running it — or start with make noauths which only requires CoreAPI and infrastructure.

Make Targets

Key targets and what they bring up:

Target Includes
make noauths Infra (lite) + CoreAPI + PlayoutAdmin + Docs
make demo Infra + CoreAPI + PlayoutAdmin + AuthAPI + TellyID
make up-infra Postgres, Redis, VerneMQ, Zitadel only
make apidocs This documentation site only

For a full list see Quickstart/Makefile.

Development Workflow

Domains are designed to be developed independently. A typical flow:

  1. Pick your domain under domain/
  2. Add or modify models in models.go — migrations run automatically on startup
  3. Write handlers in handler.go, register routes in routes.go
  4. Use pkg/response for all responses — keeps the envelope consistent across domains
  5. Rebuild CoreAPI with make noauths or restart just the CoreAPI container

External services

Castis Streamer nodes are managed via pkg/StreamerClient. Register a node via POST /streamers first, then reference it by ID when creating channels.

Documentation Status

This documentation site is actively being built alongside CoreAPI development. Pages marked complete reflect the current state of the codebase.

API Reference

Domain Status Notes
Services (Streamers) ✅ Done CRUD + ping + proxy
Channels (Playback) ✅ Done Create, delete, multi-origin
Media 🔄 In progress Upload and processing handlers exist, docs pending
Spatial ⏳ Planned Locations, venues, zones, endpoints
Provisioning ⏳ Planned Device management
Tenant ⏳ Planned Orgs and workspaces
Catalogue ⏳ Planned Playlists and media channels
Advertising ⏳ Planned Campaign scheduling
Identity ⏳ Planned Users and roles

Site & Infrastructure

  • MkDocs Material theme configured
  • Swagger UI rendering via render_swagger
  • Mermaid diagram support
  • Dark/light mode
  • documentation repo decoupled from apidocs (deprecated)
  • Nav structure finalized in mkdocs.yml
  • All domain API pages linked in nav
  • Staging environment docs (mkdocs.yml per env)

CoreAPI Codebase

  • pkg/response — unified response envelope across domains
  • pkg/StreamerClient — StreamerNode decoupled, import cycle resolved
  • Proxy endpoint for Streamer API
  • pkg/CproxyClient
  • pkg/ELBClient
  • Migrate domain/playback to pkg/response
  • Migrate domain/media to pkg/response

Branching

  • Staging branch strategy defined
  • Feature branch naming convention documented
  • CoreAPI staging environment tested against .env.staging