HiveGrid-Wireframes/hivegrid-cloud/docs/new-project.md

New Project Onboarding

Purpose

This guide is the local quick-start entrypoint for starting a new project from the boilerplate. It focuses on the current repository state: root scripts start the @toolctrl/web React Router runtime whose source lives in apps/web/app, while apps/api and apps/worker are extracted foundations for API and worker evolution. apps/api is a runtime-wired Hono API app with a canonical /v1 surface, and apps/worker is opt-in through worker environment flags.

Start with docs/quickstart.md for first-run bootstrap, then use docs/local-dev.md for day-to-day local development, service dependencies, verification, and troubleshooting.

Use this document for local setup and static verification. Browser, Playwright, Cypress, and other E2E checks are manual unless a focused run is explicitly approved.

Prerequisites

Install or provide these local dependencies before running the project:

• Node.js compatible with the repository .nvmrc when present.
• Corepack for the pinned package manager.
• pnpm@10.33.0 through Corepack.
• PostgreSQL for the Prisma-backed application database.
• Optional Redis only when running the BullMQ worker foundation.

Enable the pinned package manager:

corepack enable
corepack prepare pnpm@10.33.0 --activate

Install Dependencies

Install the workspace dependencies from the repository root:

pnpm install

Root scripts start the active @toolctrl/web React Router runtime from apps/web/app. Workspace packages such as @toolctrl/db, @toolctrl/mail, and @toolctrl/queue describe current or target boundaries, but they do not replace the web runtime for local development.

Environment Setup

Create a local environment file from the example:

cp .env.example .env

Set placeholder values for local development. Do not copy production secrets into .env.

Required local variables:

• APP_NAME: local display name for the app.
• SESSION_SECRET: placeholder-only local session secret.
• CRYPTO_SECRET: placeholder-only local encryption secret.
• DATABASE_URL: PostgreSQL connection string used by Prisma.
• APP_BASE_DOMAIN, WEB_APP_HOST, ADMIN_APP_HOST, API_HOST, and APP_PROTOCOL: split-host routing settings from .env.example.
• PORT / API_PORT: listener bind ports only; keep the example defaults unless you need a custom local port.

Transactional mail is represented by the Mailjet boundary. Keep any Mailjet API keys or webhook signing secrets as placeholder-only local values unless you are deliberately testing mail delivery with a non-production account.

PostgreSQL and Prisma Setup

Start a local PostgreSQL database, then point DATABASE_URL at that database. The active database stack is PostgreSQL through Prisma. The Prisma schema and migrations still live under prisma/, while packages/db owns the server-side Prisma client boundary and database command surface.

Apply the schema with Prisma:

pnpm exec prisma migrate dev

If you need a schema push during local bootstrap, use:

pnpm exec prisma db push

Use DIRECT_URL only when you intentionally need a direct database connection for Prisma operations. Keep both DATABASE_URL and DIRECT_URL as placeholders in documentation and local examples.

Seed and Run the Web App

Seed the local database when needed:

pnpm seed
pnpm run permissions:sync

Start the active @toolctrl/web React Router runtime from the root script:

pnpm dev

Open http://app.localhost:3000 for the tenant app and http://admin.localhost:3000 for admin. The root pnpm dev command starts only the @toolctrl/web runtime; when API work is in scope, run pnpm --filter @toolctrl/api dev separately and open http://api.localhost:3001. Seeded demo tenants and users are created only when SEED_DEMO_DATA=true is set for a disposable local database; those accounts must not be reused as production credentials.

Optional Worker Redis

Redis is not required for the default web quick start. Enable worker execution only when you are working on queue-backed behavior:

• Set WORKER_ENABLED=true.
• Set BULLMQ_REDIS_URL to a local Redis connection placeholder.
• Set WORKER_QUEUE_GROUP to the queue group you are testing, such as general, mail, or plugin.
• Use REDIS_URL only as a platform-binding fallback when that is the environment contract being tested.

apps/worker exits unless WORKER_ENABLED=true. It now contains active BullMQ processors for optional background surfaces, including general maintenance/notification/outbox work, mail-bound jobs, and the isolated plugin invocation queue. Some feature-specific processors remain behind their own environment gates, so do not treat Redis as mandatory for every new project user.

Static Verification Commands

Run scoped non-E2E checks before handing off local setup changes:

test -s docs/new-project.md
grep -Eq "Corepack|pnpm@10\.33\.0|DATABASE_URL|PostgreSQL|Prisma|WORKER_ENABLED|BULLMQ_REDIS_URL|manual" docs/new-project.md
pnpm run verify:ci-baseline
pnpm run verify:gitea-ci-workflow

Use focused lint or test commands for files you changed. Full browser and E2E suites are not part of Auto-Mode task verification unless explicitly approved for that exact run.

Manual Checks

After the static checks pass, use manual checks only for human-facing confidence:

1. Confirm .env contains only local placeholders and no real deployment secrets.
2. Confirm PostgreSQL is reachable through DATABASE_URL.
3. Confirm Prisma migration or push completed successfully.
4. Confirm pnpm seed created local development data and pnpm run permissions:sync aligned static roles and permissions.
5. Confirm pnpm dev starts the @toolctrl/web React Router runtime in apps/web/app and serves the configured app/admin hosts.
6. If worker work is in scope, confirm Redis is running and the worker is started with WORKER_ENABLED=true and BULLMQ_REDIS_URL set.

Keep Playwright, Cypress, browser automation, and other E2E execution manual by default. Record the scenario and result in handoff notes instead of adding automatic E2E runs to local onboarding.