# Developers

Tilecast is an AGPL-3.0-only project in the [`gbyo/tilecast` repository](https://github.com/gbyo/tilecast). The repository contains the server, Studio, Android and Linux Players, shared packages, deployment files, and this documentation site.

## Repository layout

- tilecast/
  - apps/ Product applications.
    - server/ Go server, HTTP API, and database migrations.
    - dashboard/ React and TypeScript management app, Tilecast Studio.
    - player-android/ Kotlin and Jetpack Compose Player for Android TV devices.
    - player-linux/ Electron Player for Linux kiosk devices.
    - docs/ Astro and Starlight public documentation site.
  - packages/ Shared design tokens and application contracts.
  - deploy/ Docker deployment and optional network integrations.
  - docs/ Engineering references, API descriptions, and implementation contracts.

## Run the server and Studio locally

You need Go (use the version in `apps/server/go.mod`), Node.js with npm, and a PostgreSQL database. From the repository root:

1. Install workspace and Go dependencies:

   ```sh title="Repository root · Install dependencies"
   make bootstrap
   ```

2. Set `TILECAST_DATABASE_URL` to a development database Tilecast can use:

   ```sh title="Set the development database"
   export TILECAST_DATABASE_URL='postgres://localhost:5432/tilecast?sslmode=disable'
   ```

3. Start the Go server in one terminal:

   ```sh title="Terminal 1 · Start the server"
   make dev-server
   ```

4. Start the Vite development server in a second terminal:

   ```sh title="Terminal 2 · Start Studio"
   make dev-dashboard
   ```

To explore Studio with sample data instead of an empty database, [run a demo installation](demo-mode/).

The Go server applies pending migrations during startup. Complete the one-time Owner setup in Studio when using a new database. Vite reloads dashboard changes; restart the Go server after changing server code. Server settings are read from `TILECAST_*` environment variables; [`deploy/docker/.env.example`](https://github.com/gbyo/tilecast/blob/main/deploy/docker/.env.example) lists the deployment settings.

## Check and build changes

From the repository root, `make check` runs the repository's documented format, lint, test, and static checks. `make build` builds the dashboard bundle, server binary, and Android debug APK. Security reports follow the private process in the repository's [Security Policy](https://github.com/gbyo/tilecast/blob/main/SECURITY.md).

[Read the contribution guide](https://github.com/gbyo/tilecast/blob/main/CONTRIBUTING.md)

## Work on the public docs

The docs site is an npm workspace. Run these commands from the repository root:

```sh title="Repository root · Docs commands"
npm run docs:dev
npm run docs:check
npm run docs:build
```

Follow the [documentation style guide](https://github.com/gbyo/tilecast/blob/main/apps/docs/STYLE.md). The docs build also checks internal links.

## Technical references

- [HTTP API overview](../reference/api/) explains the shared API contract and links to the OpenAPI description.
- [Development setup](https://github.com/gbyo/tilecast/blob/main/docs/development.md) covers local database and migration workflows.
- [Architecture](https://github.com/gbyo/tilecast/blob/main/docs/architecture.md) describes the server and application boundaries.
- [Android Player development](https://github.com/gbyo/tilecast/blob/main/docs/android-development.md) covers Android build and device workflows.