Repository Guidelines

Project Structure & Module Organization

This repo currently holds the product spec in

roadmap.md

. As implementation lands, mirror the Cloudflare-first architecture:

```
apps/web/
```
– React + Vite front end with Tailwind and GSAP animation utilities. Keep shared UI primitives in
```
apps/web/src/components
```
.
```
apps/admin/
```
– Isolated Vite React app for the admin dashboard. Only staff-facing routes live here; reuse shared primitives via
```
@monologue/shared
```
where possible.
API clients stay scoped to each app and infer their types from
```
@monologue/db/schema
```
; avoid re-exporting shared HTTP helpers.
```
workers/api/
```
– Hono worker entrypoint with route handlers under
```
workers/api/routes
```
and shared services in
```
workers/api/src
```
.
```
packages/db/
```
– Drizzle ORM schemas and Zod contracts in
```
packages/db/schema
```
, migrations generated to
```
drizzle/
```
, and shared Zod types colocated with their tables. Store media adapters in
```
packages/shared/
```
when they are reused between worker and client. Bundle soundtrack audio and supporting JSON manifests with the client apps (e.g., under each app's
```
public/
```
directory) until remote storage becomes necessary. Treat these manifests as version-controlled static data; do not plan admin or worker write flows for them.

Build, Test, and Development Commands

Run

npm install

(or

pnpm install

) from repo root to bootstrap workspaces. Use

npm run web:dev

for the Vite dev server with hot reload,

npm run admin:dev

for the isolated admin UI on port 5174, and

npm run worker:dev

to launch the Hono worker locally through

wrangler dev

. Build the deployable bundles via

npm run build

, which runs the web and admin production builds and

wrangler deploy --dry-run

. After any schema change run

npm run drizzle:generate

followed by

npm run d1:migrate

to keep the local database in sync. Apply schema updates with

npm run db:migrate

(

wrangler d1 migrations apply

). Format and lint before pushing with

npm run lint

and

npm run format

Dependency Management

Treat the repo as a single monorepo: when two apps or packages share a dependency, hoist it into the workspace root and reference it from each module's

package.json

via a

workspace:

specifier instead of duplicating installs. Share API contracts by importing Zod schemas/inferred types from

@monologue/db/schema

; individual apps should implement their own HTTP clients.

Coding Style & Naming Conventions

TypeScript is required in all runtime code. Use 2-space indentation, PascalCase for React components, camelCase for functions and variables, and kebab-case for file names except components (PascalCase). Prettier and ESLint should be run via

npm run lint

and

npm run format

. Keep worker handlers pure and move Cloudflare bindings behind helper modules for easier testing.

Testing Guidelines

Adopt Vitest for both frontend and worker packages; colocate specs beside source files as

*.test.ts

. Use Miniflare when mocking Cloudflare bindings. Target 80% statement coverage on

npm run test -- --coverage

, and include regression fixtures for dialogue formatting and tag parsing. Snapshot tests belong in

__snapshots__

directories.

Commit & Pull Request Guidelines

There is no commit history yet; start with Conventional Commits (

feat:

fix:

chore:

) so changelog tooling can work later. Keep PRs focused on a single vertical slice, link the relevant section of

roadmap.md

, and attach screenshots for UI changes or logs for worker endpoints. Require green CI (lint + test) before requesting review, and document any secret or Wrangler binding changes in the PR description.

Security & Configuration Tips

Store API keys with

wrangler secret put

and avoid committing

.env

files. With R2 deferred, keep bundled media assets organized in the repo, document manifest edits in PRs, and rotate admin bearer tokens on a regular cadence. When adding new bindings, update both

wrangler.toml

and the deployment checklist in the PR.

Admin Dashboard Access

Serve the admin bundle from
```
admin.<domain>
```
(or Cloudflare Access) via dedicated Wrangler routes so the dashboard never ships with the public SPA.
Mirror that isolation locally: run the admin Vite server separately (
```
npm run admin:dev
```
) and proxy to the same API worker for mutations.
Enforce role checks in worker middleware; the admin UI should assume protected routes still validate bearer tokens.

Project Structure & Module Organization

This repo currently holds the product spec in

roadmap.md

apps/web/

– React + Vite front end with Tailwind and GSAP animation utilities. Keep shared UI primitives in

apps/web/src/components

apps/admin/

– Isolated Vite React app for the admin dashboard. Only staff-facing routes live here; reuse shared primitives via

@monologue/shared

where possible.

API clients stay scoped to each app and infer their types from

@monologue/db/schema

; avoid re-exporting shared HTTP helpers.

workers/api/

– Hono worker entrypoint with route handlers under

workers/api/routes

and shared services in

workers/api/src

packages/db/

– Drizzle ORM schemas and Zod contracts in

packages/db/schema

, migrations generated to

drizzle/

, and shared Zod types colocated with their tables. Store media adapters in

packages/shared/

when they are reused between worker and client. Bundle soundtrack audio and supporting JSON manifests with the client apps (e.g., under each app's

public/

directory) until remote storage becomes necessary. Treat these manifests as version-controlled static data; do not plan admin or worker write flows for them.

Admin Dashboard Access

Serve the admin bundle from

admin.<domain>

(or Cloudflare Access) via dedicated Wrangler routes so the dashboard never ships with the public SPA.

Mirror that isolation locally: run the admin Vite server separately (

npm run admin:dev

) and proxy to the same API worker for mutations.

Enforce role checks in worker middleware; the admin UI should assume protected routes still validate bearer tokens.

Repository Guidelines

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Dependency Management

Coding Style & Naming Conventions

Testing Guidelines

Commit & Pull Request Guidelines

Security & Configuration Tips

Admin Dashboard Access

Related Skills

Markdown Converter

Nano Banana Pro

1password

Repository Guidelines

Project Structure & Module Organization

Build, Test, and Development Commands

Dependency Management

Coding Style & Naming Conventions

Testing Guidelines

Commit & Pull Request Guidelines

Security & Configuration Tips

Admin Dashboard Access