Project structure - The Stacks docs

The Stacks is split across two repositories:

thestacks.org (this one): the website, the MyST renderer, and hosted services like PDF generation.
Raven: the backend API and its database.

The frontend gets its data from Raven’s HTTP API (API docs). See the sub-pages in these docs, as well as each repository’s README, for more details.

This repository¶

Raven is the backend for a new publishing platform and powers The Stacks.

API Documentation¶

The API documentation is available at [base url]/api/v1/docs

Deployment¶

The easiest way to deploy Raven is to use the docker-compose setup from deploy/local/. See the deploy README and follow the instructions for the Full deployment.

Workspace Structure¶

This is a pnpm monorepo. Packages are defined in pnpm-workspace.yaml.

Path	Package	Description
`docusaurus/`	`@raven/docusaurus`	Docusaurus documentation server
`backend-ts/`	`@raven/backend-ts`	TypeScript/Hono HTTP server
`eslint-config/`	`@raven/eslint-config`	Shared linter configuration
`cli/`	`@raven/cli`	`raven` command-line interface
`tests/`	`@raven/integration-tests`	Integration tests (Docker-based)
`parity-tests/`	`@raven/parity-tests`	Backend tests (Docker-based)

There are additionally the following folders that are not packages.

Path	Description
`backend/`	Legacy Python/Flask backend. Not used anymore
`deploy`	Configuration and scripts supporting deployment

Development¶

There are two ways to get an environment set up for development.

Use the provided devcontainer
Develop on the metal of your machine

Develop in Devcontainer¶

Follow the instructions in the devcontainer README

Develop on Metal¶

Prerequisites¶

Node.js >= 24
pnpm >= 11
- Using corepack: npm install --global corepack@latest && corepack enable pnpm
Docker
VSCode

Common Commands¶

Run commands from the repo root unless otherwise noted.

TypeScript Backend¶

In the backend-ts folder, you can run these commands.

# Migrate the DB
MIGRATION_DATABASE_URI="mysql://root:root_password@localhost:4306/raven?charset=utf8mb4" pnpm db:migrate

# Run the backend
pnpm dev

See backend-ts README.md for more.

Testing¶

# Run all tests across the workspace
pnpm test

# Run backend-ts unit tests only
pnpm --filter @raven/backend-ts test

# Run integration tests (spins up Docker services)
pnpm --filter @raven/integration-tests test

# Run integration tests in watch mode
pnpm --filter @raven/integration-tests test:watch

Linting & Formatting¶

# Lint all packages
pnpm lint

# Lint a specific package
pnpm --filter @raven/backend-ts lint

# Format all files
pnpm format

# Check formatting without writing
pnpm format:check

Type Checking¶

# Type-check all packages
pnpm typecheck

# Type-check a specific package
pnpm --filter @raven/backend-ts typecheck

Database (Drizzle ORM)¶

Run these from the backend-ts/ directory or with --filter:

# Generate migrations from schema changes
pnpm --filter raven-backend-ts db:generate

# Apply migrations
pnpm --filter raven-backend-ts db:migrate

# Push schema directly (dev only)
pnpm --filter raven-backend-ts db:push

Contributing¶

Please read our contribution guidelines before submitting pull requests.

License¶

MIT License