OptiFeed

Precision feeding and pond management for African catfish farms. Built as PakaonAI, a capstone project for ISUFST Dingle Campus.

Documentation

Start at docs/README.md — the map of the plan, the decisions, the workflow and the runbooks. It is the entry point for humans and agents; the rules themselves live in CONTRIBUTING.md, HANDOFF.md and docs/deployment-workflow.md.

Tech Stack

• Framework: Next.js 16 (App Router)
• Database & Auth: Supabase (Postgres + Auth)
• ORM: Prisma
• i18n: next-intl (English, Hiligaynon, Tagalog)
• Styling: Tailwind CSS 4
• UI Components: shadcn/ui
• Monorepo: pnpm workspaces
• Node: 22.12 or newer (@commitlint/cli 21 requires it; CI runs Node 22)
• Linting/Formatting: Biome
• Git Hooks: Husky + lint-staged + commitlint

Setup

1. Install dependencies:

   pnpm install
   

2. Copy apps/web/.env.example to apps/web/.env and fill in your Supabase credentials:

   • DATABASE_URL (pooled connection)
   • DIRECT_URL (direct connection for migrations)
   • NEXT_PUBLIC_SUPABASE_URL
   • NEXT_PUBLIC_SUPABASE_ANON_KEY
   • SUPABASE_SERVICE_ROLE_KEY

3. Generate the Prisma client. pnpm install runs this through the guarded root postinstall when apps/web/prisma/schema.prisma exists; rerun it after pulling a schema change:

   pnpm prisma:generate
   

4. Run database migrations:

   pnpm prisma:migrate
   

5. Start the development server:

   pnpm dev
   

Scripts

Script	Description
pnpm dev	Start the Next.js dev server
pnpm build	Build the Next.js app for production
pnpm lint	Run Biome lint checks
pnpm lint:fix	Run Biome lint checks with auto-fixes
pnpm format	Format files with Biome
pnpm prisma:generate	Generate the Prisma client
pnpm prisma:migrate	Run Prisma migrations
pnpm security:overrides	Verify the pnpm security pins resolve as intended
pnpm typecheck	Run TypeScript checks across the workspace

API contract

All HTTP+JSON endpoints follow API_REGULATION.md: one { data, meta } / { error } envelope, a versioned /api/v1 tree, the 300/400 ms budgets, Server-Timing and X-Request-Id on every response (including errors), and a recorded sunset for the legacy tree.

Command	Purpose
pnpm api:check	Static conformance: every route instrumented, list queries bounded, declarations present. Runs in CI.
pnpm api:live -- --mode warn	Live contract + latency suites. Needs API_BASE_URL and API_TEST_COOKIE or API_TEST_BEARER.
pnpm api:live -- --mode fail	Enforcement mode. Coverage below 90 % fails in both modes.

Endpoint inventory and documented exemptions live in API_REGULATION.md; the ranked burn-down is docs/api-regulation-backlog.md.

Branch workflow

Development moves through four stages; only two of them deploy.

feature/* ──PR──▶ develop ──PR──▶ staging ──PR + Jeff──▶ main
                     │              │                     │
               validate only   staging deploy      production deploy

• Work on a short-lived branch from develop; open PRs into develop.
• develop is the shared integration branch and never deploys.
• staging is the default branch and the release candidate; it deploys the staging environment.
• main is production and is only advanced by a PR from staging, approved and merged by Jeff.

Full rules: CONTRIBUTING.md. Pipeline details, deployment policy, and known blockers: docs/deployment-workflow.md.

Contributing

Start with CONTRIBUTING.md for the workflow, then HANDOFF.md for repository orientation and the database safety rules. Never run prisma migrate reset against production.