AGENTS.md · Chocobozzz/PeerTube

Sections

1. Repository Structure
2. Build & Development Commands
3. Code Style & Conventions
4. Architecture Notes
5. Testing Strategy
6. Security & Compliance
7. Agent Guardrails
8. Extensibility Hooks
9. Further Reading

First lines (shown under the repo's AGPL-3.0 license)

# Project Overview

PeerTube is an open-source, ActivityPub-federated video streaming platform
that uses P2P technology directly in web browsers. Developed by Framasoft
under the AGPL-3.0 license, it provides a decentralized alternative to
centralized video platforms. The server is a Node.js/Express API with a
Sequelize ORM (PostgreSQL), background job processing (BullMQ/Redis),
ActivityPub federation, and an Angular SPA client. Video transcoding is
handled via FFmpeg, with optional distributed runners.

## Repository Structure

- **apps/** — Standalone CLI applications (`peertube-cli`, `peertube-runner`)
- **client/** — Angular frontend SPA (separate build system)
- **config/** — YAML configuration files for dev, test, and production
- **packages/** — Shared workspace packages (monorepo):
  - `core-utils/` — Shared pure-JS utilities
  - `ffmpeg/` — FFmpeg wrapper library
  - `models/` — Shared TypeScript interfaces and API types
  - `node-utils/` — Node.js-specific helpers
  - `server-commands/` — HTTP client helpers used by tests
  - `tests/` — Full test suite (API, CLI, plugins, feeds, etc.)
  - `transcription/` — Speech-to-text engine integration
  - `transcription-devtools/` — Transcription benchmarking tools
  - `types-generator/` — Generates the public `@peertube/peertube-types`
    package
  - `typescript-utils/` — Generic TypeScript helpers
- **scripts/** — Build, CI, dev, release, and i18n shell scripts
- **server/** — Backend entry point and core application code
  - `server.ts` — Process entry point
  - `core/controllers/` — Express route handlers (API, ActivityPub,
    feeds, tracker)
  - `core/models/` — Sequelize database models (14 categories)
  - `core/lib/` — Business logic (transcoding, live, job queue,
    ActivityPub, plugins, runners, notifications, etc.)
  - `core/middlewares/` — Auth, rate-limiting, validation, caching, CSP
  - `core/helpers/` — Utility functions and custom validators
  - `core/initializers/` — App bootstrap, constants, DB migrations,
    config loading
  - `core/types/` — Internal TypeScript type augmentations
- **support/** — Documentation, Docker, Nginx configs, OpenAPI spec

## Build & Development Commands

### Prerequisites

- Node.js >= 22.x
- pnpm >= 10.9 (do **not** use npm or yarn for install)
- PostgreSQL >= 14 with `pg_trgm` and `unaccent` extensions
- Redis >= 6.x
- FFmpeg >= 4.3
- Python >= 3.8 (for some test tooling)

### Install dependencies

```bash
pnpm install --frozen-lockfile
```

### Build

```bash
# Build server only (backend work)
npm run build:server

# Build full application (server + client)
npm run build

# Build tests
npm run build:tests

# Build individual apps
npm run build:peertube-cli
npm run build:peertube-runner
```

### Development

```bash
# Server-only with hot reload (recommended for backend work)
npm run dev:server        # http://localhost:9000

# Full stack (server + Angular client)
npm run dev               # server :9000, client :3000

# Dev credentials: root / test
```

### Lint & type-check

```bash
# Full lint (oxlint + OpenAPI validation)
npm run lint

# Oxlint only
npm run oxlint

# Validate OpenAPI spec
npm run swagger-cli -- validate support/doc/api/openapi.yaml

# TypeScript compilation check
npm run tsc -b server/tsconfig.json
```

### Run in production

```bash
npm run start              # server + client
npm run start:server       # server only (--no-client)
```

## Code Style & Conventions

### Formatting (enforced by Oxlint)

| Rule                | Value                                 |
|---------------------|---------------------------------------|
| Semicolons          | **never** (`@stylistic/semi`)         |
| Max line length     | 140 characters                        |
| Quotes              | Single quotes (TypeScript default)    |
| Array brackets      | Spaces inside `[ 'a', 'b' ]`         |
| Trailing newline    | Required (`eol-last`)                 |
| Indentation         | 2 spaces (TypeScript convention)      |

### Naming patterns

- Database models: `VideoModel`, `UserModel` — PascalCase + `Model` suffix
- Internal type aliases: `MVideo`, `MVideoWithChannel` — `M` prefix for
  Sequelize model types with specific association requirements
- Controllers: one file per resource, registered in parent `index.ts`
- Validators: mirror controller structure under
  `server/core/middlewares/validators/`

### Controller pattern

```typescript
import express from 'express'
import { apiRateLimiter, asyncMiddleware } from '../../middlewares/index.js'

const router = express.Router()
router.use(apiRateLimiter)  // always include rate limiting

router.get('/:id',
  validationMiddleware,     // always validate inputs
  asyncMiddleware(handler)  // always wrap async handlers
)
```

Secondary processes (`--role=secondary`) serve every route. A route that needs a state only the primary
process has (its file system, data kept in its memory, live sessions, the tracker...) must start with the
`primaryOnly` middleware, before any side effect: a secondary answers `421` and nginx replays the request on
the primary. Requests whose body nginx streams (`proxy_request_buffering off` locations) cannot be replayed:
route them to `backend` in the `$peertube_pool` map of `support/nginx/peertube`.

### Commit messages

No formal commit-message template.

### Oxlint config