Benkyou

Benkyou turns long videos into focused study workspaces: chapters, notes, bookmarks, progress, and resume state.

The Open Beta is a local-first learning workspace. The first screen is the app itself: paste a YouTube URL, create or open a sample study workspace, and start learning.

Workspace

apps/
  web/          TanStack Start web app

packages/
  core/         Framework-free product logic
  db/           Drizzle schema, migrations, seeds, and DB helpers
  types/        Shared public types and API contracts
  ui/           Reusable React UI components

docs/           Public product and implementation docs

Requirements

• Node.js >=20.19
• pnpm 10.33.4
• Postgres connection string for database-backed development

Setup

pnpm install
cp apps/web/.env.example apps/web/.env.local

Fill in the values in apps/web/.env.local. For the first local run, set:

• DATABASE_URL: Postgres connection string for the app database.
• BETTER_AUTH_SECRET: secret used by Better Auth.
• BETTER_AUTH_URL: local app URL, usually http://localhost:3000.
• PUBLIC_SITE_URL: public canonical URL for SEO metadata, robots, and sitemap.
• VITE_PUBLIC_POSTHOG_KEY: optional PostHog project key; leave blank to disable analytics for self-hosting.
• VITE_PUBLIC_POSTHOG_HOST: optional PostHog host, default https://us.i.posthog.com.
• VITE_PUBLIC_POSTHOG_DISABLED: set to true to disable analytics even when a PostHog key is configured, default false.
• VITE_PUBLIC_POSTHOG_ENABLE_IN_DEVELOPMENT: set to true only when you want local development to send analytics events, default false.
• GENERATION_RATE_LIMIT_MAX: optional course generation quota, default 5.
• GENERATION_RATE_LIMIT_WINDOW_HOURS: optional quota window, default 24.

AI provider values can stay blank while using creator timestamps or sample data. Set AI_PROVIDER=openai and AI_API_KEY when AI chapter fallback is enabled.

Development

Run the full workspace:

pnpm dev

Run only the web app:

pnpm --filter @benkyou/web dev

Open http://localhost:3000.

Checks

pnpm check
pnpm check-types
pnpm build

Package-specific checks can be run with pnpm --filter <package> <script>.

Contributing

Benkyou welcomes roadmap-aligned contributions to the self-hostable learning workspace.

• Read CONTRIBUTING.md before opening issues or pull requests.
• Follow the Code of Conduct.
• Use SUPPORT.md for questions, bugs, and support channels.
• Report vulnerabilities privately using SECURITY.md.
• See ROADMAP.md for the public product direction.

Contributions should improve the self-hostable Benkyou learning workspace. Hosted-only business operations, billing, private infrastructure, internal analytics, and admin tooling are outside the scope of this repository. The app may include optional, no-op-by-default analytics integrations for operators who configure them explicitly.

Self-hosting

Copy the root template and replace every placeholder secret:

cp .env.example .env

Do not commit .env. Set POSTGRES_PASSWORD, BETTER_AUTH_SECRET, and any provider keys such as AI_API_KEY to real private values before production use.

Run Benkyou with Docker Compose:

docker compose up --build

The Compose stack starts Postgres, builds the web app, runs database migrations, and serves Benkyou at http://localhost:3000. Only the web service publishes a host port by default. Postgres stays on the internal Compose network and is reached by the app as db.

Useful production checks:

curl http://localhost:3000/api/health

Architecture

• Keep apps/web thin: routes, layouts, server functions, auth/session wiring, environment wiring, and page composition.
• Put reusable product logic in packages/core.
• Put shared public contracts in packages/types.
• Put reusable React UI in packages/ui.
• Put persistence and schema code in packages/db.

See AGENTS.md for implementation rules and docs/mvp-implementation-checklist.md for the early execution plan.

License

Benkyou is released under the MIT License.