Skip to content
AltBrain

BaghBaan

Source catalog · Knowledge graph

Facts

FactValue
Statusdormant
Hosting platformcloudflare
Repositoryhttps://github.com/meta4m/baghbaan
Tech stacklanguage: typescript, framework: next-js, ui: react, ui_kit: shadcn-ui, styling: tailwindcss, database: cloudflare-d1, storage: cloudflare-r2, hosting: cloudflare-pages, ci: github-actions, testing: vitest
Tagsplants, plant-care, mobile, pwa, household, pakistan, qr-codes
Last audited2026-09-15
Upstream dependenciesNone declared
Downstream dependenciesNone declared

Secrets manifest

Key names and metadata only. Encrypted records are available in this project’s vault below.

KeyDescriptionEnvironmentsRequired
CLOUDFLARE_API_TOKENCloudflare API token (Pages Edit + D1 Edit) used by the GitHub Actions workflows to run remote D1 migrations and deploy the baghbaan Cloudflare Pages projectproduction, stagingYes
JWT_SECRETHMAC signing secret for baghbaan_session JWT cookies read from process.env in src/lib/auth.ts; the code falls back to an insecure hardcoded default when unset, so it must be provisioned for any real deploymentproduction, developmentYes

Overview

Project Overview: BaghBaan

1. Executive Summary

  • Mission: A mobile-first plant care PWA for Pakistan’s regional flora — track household plants, share care across family members, and label plants with QR stickers, with AI species identification and disease diagnosis planned in the design docs.
  • Target Audience: Pakistani households (Urdu-first per the handoff doc; the current UI is English) managing houseplants, balconies, and gardens on mid-range Android phones.
  • Primary Maintainer: The operator (meta4m) — private solo project.

2. Current Status & Roadmap

  • Lifecycle State: dormant — the entire history is 3 commits from a single sprint on 2026-07-31 (CI/CD setup, docs, then “Phase 1 - Next.js setup, auth, plant CRUD, QR codes”); no commits in the ~7 weeks since.
  • Deployment reality check: https://baghbaan.pages.dev (declared in CI config and SETUP_GUIDE.md) returned HTTP 404 on 2026-09-15 — the Pages project is not currently serving.
  • The repo’s CHECKLIST.md roadmap (auth, plant CRUD, care schedules, AI agents, Urdu) is largely unexecuted beyond Phase 1; AGENTS.md still claims “no code yet” (stale). Docs (47 KB ARCHITECTURE.md, 70 KB UI_UX_SPECIFICATION.md) significantly outpace the implementation.

3. Core Capabilities

  • Household auth (src/app/api/auth/*): register/login with generated account ID (ACC-YYYY-XXXX) + 4-digit PIN, bcrypt hashing, JWT in an HttpOnly baghbaan_session cookie (24 h), admin/member/viewer roles.
  • Plant CRUD (src/app/api/plants/route.ts): list/create plants per household with photo upload to R2 and a per-plant care schedule.
  • QR labels (src/lib/qrcode.ts): branded QR PNG per plant deep-linking to /plant/<id>, uploaded to R2.
  • PWA shell: public/manifest.json, Tailwind 4 + shadcn/ui + Framer Motion UI; dashboard page currently renders mock data.
  • CI/CD (.github/workflows/): dev/prod pipelines that generate wrangler.toml from a template, run remote D1 migrations, and deploy to Cloudflare Pages; D1/R2/Vectorize dev+prod resources are provisioned with IDs recorded in SETUP_GUIDE.md.
  • Planned, not built: Durable Object agents, image-processing queue, Vectorize search, Workers AI diagnosis, care calendar, Urdu localization — bindings exist in wrangler.template.toml but no code references them.

4. Key References

  • Repository: meta4m/baghbaan (private)
  • Production URL: https://baghbaan.pages.dev is declared in CI config, but returned 404 on 2026-09-15 — treat as not deployed/unverified.
  • Architecture Docs: architecture.md · Deployment Guide: deployment.md

Architecture

Architecture & System Design: BaghBaan

1. System Topology

graph TD
    User[Household browser / PWA] --> Next[Next.js 16 App Router<br/>landing, auth pages, dashboard, plants/add]
    Next --> API[API routes<br/>/api/auth/* and /api/plants]
    API --> Auth[Auth lib<br/>bcrypt + JWT cookie]
    API --> Db[(Cloudflare D1<br/>baghbaan-db-dev / -prod<br/>8 tables)]
    API --> R2[(Cloudflare R2<br/>baghbaan-images-dev / -prod)]
    API --> QR[QrCodeGenerator<br/>qrcode npm pkg]
    GH[GitHub Actions<br/>push main/dev/feature/*] -->|migrate + build + wrangler pages deploy| Pages[Cloudflare Pages project baghbaan]
    Planned[Planned: DO agents, image queue,<br/>Vectorize, Workers AI] -.->|bindings declared, no code| API

2. Core Components & Subsystems

  • App shell (src/app/): client-component pages — landing (feature cards), login/register, dashboard (mock plants), add-plant form; layout.tsx sets PWA metadata.
  • API layer (src/app/api/): auth/register, auth/login, auth/logout, plants (GET list / POST create). Auth guard = session cookie → Auth.verifyToken.
  • Service libs (src/lib/): auth.ts (bcrypt + JWT + cookie helpers), database.ts (parameterized D1 queries for all 8 entities), storage.ts (R2 upload under plants/, diagnoses/, qr/ key prefixes), qrcode.ts (plant deep-link QR PNGs).
  • Config: wrangler.template.toml with {{PLACEHOLDERS}} filled by CI sed — binds D1 (DB), R2 (IMAGES), plus declared-but-unused AI, Vectorize, Durable Objects, and Queue bindings.
  • Migrations (migrations/, seeds/, scripts/migrate.sh): policy is dev DB gets migrations + seeds, prod DB gets structural migrations only, never data.

3. Data Flow & Storage Contracts

  • Storage: Cloudflare D1 (SQLite) is the only persistent store — 8 tables: households, members, plants, care_schedules, care_tasks, diagnoses, reminders, qr_codes (migrations/0001_initial_schema.sql). R2 holds plant photos, thumbnails, diagnosis photos, and QR PNGs addressed by the public R2_PUBLIC_URL. No localStorage usage; no Vectorize data yet.
  • Add-plant flow: multipart POST → photo uploaded to R2 (plants/<household>/<plant>/original_<ts>) → QR generated for <APP_URL>/plant/<id> and uploaded to qr/<household>/<plant>.png → plant + care schedule rows inserted in D1.
  • Auth flow: register → account ID + bcrypt password/PIN hashes in households → JWT (householdId, memberId, role) in HttpOnly cookie.
  • Flagged gap: API routes read bindings via process.env as Env (DB, IMAGES), which only exist in the Cloudflare runtime — plain next dev has no documented bindings emulation, and the deploy path (wrangler pages deploy .next with no @cloudflare/next-on-pages adapter in dependencies) makes it unverified whether the API routes run on Pages at all.

4. Architectural Decision Records (ADRs)

ADR-01: Household PIN auth instead of OAuth
  • Context: Family sharing for low-friction users; one account, up to 5 members (admin/member/viewer).
  • Decision: Generated account ID + 4-digit PIN, bcrypt hashes, self-rolled JWT sessions — no OAuth provider.
  • Consequences: Very simple UX and zero third-party deps for identity; but JWT_SECRET management is now the app’s responsibility (with an insecure code fallback), and there is no MFA/recovery path.
ADR-02: All-in on Cloudflare free tier
  • Context: Target $0/month for 1–5K users; docs mandate free-tier limits.
  • Decision: Next.js PWA on Cloudflare Pages with D1 + R2 (+ planned Workers AI, Vectorize, DOs, Queues), split dev/prod resources.
  • Consequences: Negligible cost and tight service integration; Next.js server features on Pages are nontrivial (see flagged gap) and the stack couples the app to Cloudflare primitives.
ADR-03: QR sticker per plant
  • Context: Physical plants need a fast link to their care page.
  • Decision: Every plant gets a branded QR PNG (deep link /plant/<id>) generated server-side and stored in R2.
  • Consequences: Print-and-stick workflow; but the /plant/<id> detail route is not yet implemented, so links currently have no destination.
ADR-04: CI-generated wrangler config from a template
  • Context: Two environments with different D1/R2/Vectorize resource IDs; IDs shouldn’t live in git.
  • Decision: wrangler.template.toml + sed substitution in GitHub Actions using environment secrets (D1_PROD_ID, R2_*_PUBLIC_URL, …).
  • Consequences: Repo stays clean of environment IDs; local manual deploys require reconstructing wrangler.toml by hand, and config drift lives only in workflow files.

Deployment

Deployment & Operational Runbook: BaghBaan

1. Hosting & Environments

EnvironmentPlatformURL / EndpointAuto-Deploy Branch
ProductionCloudflare Pages (baghbaan)https://baghbaan.pages.dev — returned 404 on 2026-09-15, not currently servingmain (deploy-prod.yml)
PreviewCloudflare Pages (baghbaan)https://<sha>.baghbaan.pages.devdev, feature/**, fix/** (deploy-preview.yml)
Local devNext.js dev serverhttp://localhost:3000N/A

2. Prerequisites & Toolchain

  • Node.js 22 + npm; Wrangler 4.x (devDependency) authenticated to the Cloudflare account holding the provisioned resources.
  • Cloudflare resources (IDs in SETUP_GUIDE.md): D1 baghbaan-db-dev/baghbaan-db-prod, R2 baghbaan-images-dev/baghbaan-images-prod, Vectorize baghbaan-vector-dev/baghbaan-vector-prod; GitHub environments for secrets.
  • GitHub CLI (gh) for managing environment secrets.

3. Local Development Setup

Terminal window
git clone https://github.com/meta4m/baghbaan.git
cd baghbaan
npm install
npm run dev              # next dev — UI pages only
npm run db:migrate       # remote D1 dev DB: migrations + seeds (needs wrangler auth)
npm run lint && npm run typecheck

Caveat: API routes expect D1/R2 bindings via process.env that only exist in the Cloudflare runtime — the repo documents no local bindings emulation (wrangler pages dev), so API routes will fail under plain next dev.

4. Environment & Secrets Provisioning

Refer to spec.yml for declared secret keys.

  • Secret Injection: Retrieve ciphertext from the 2brain vault and decrypt locally into .env.local.
  • CI (GitHub environment secrets): CLOUDFLARE_API_TOKEN (Pages + D1 edit) and JWT_SECRET (runtime). ⚠️ Mismatch flag: SETUP_GUIDE.md says environments baghbaan-preview/baghbaan-production were created, but the workflows reference BaghBaan Preview/BaghBaan Production — names must match or secrets won’t resolve.
  • Non-secret config (kept in GitHub secrets purely for templating): CLOUDFLARE_ACCOUNT_ID, D1_DEV_ID, D1_PROD_ID, R2_DEV_PUBLIC_URL, R2_PROD_PUBLIC_URL, ENVIRONMENT; runtime NEXT_PUBLIC_APP_URL.

5. Deployment Commands

Terminal window
npm run build                 # next build
npm run deploy                # wrangler pages deploy .next --project-name=baghbaan
npm run deploy:preview        # same, --branch=dev
npm run db:migrate:prod       # structural migrations on baghbaan-db-prod (seeds never run on prod)
npm run db:migrate            # dev DB: migrations + seed data

Primary path is GitHub Actions: push to dev/feature/**/fix/** → preview deploy; merge to main → prod deploy (migrate → generate wrangler.toml from template → build → wrangler pages deploy → Playwright smoke). ⚠️ The repo contains no test files or playwright.config.*, so the test:smoke CI stage is expected to fail as-is.

6. Verification & Health Checks

  • gh run list — both workflows should be green end-to-end.
  • curl -s -o /dev/null -w "%{http_code}" https://baghbaan.pages.dev — expected 200; got 404 on 2026-09-15, so the deployment is currently broken or never completed.
  • In-app: register a household, log in with account ID + PIN, add a plant, confirm the QR code appears.
  • wrangler d1 list / wrangler r2 bucket list to confirm resources still exist.

7. Incident Response & Rollback

  • Rollback: redeploy the last good revision — git checkout <good-sha> && npm run deploy — or use the per-deployment immutable *.baghbaan.pages.dev URLs visible in the Pages dashboard.
  • Bad data / D1: migrations are forward-only via scripts/migrate.sh (explicit --dev/--prod targeting); investigate with wrangler d1 execute baghbaan-db-prod --remote --command "..." before any schema action. Prod never receives seed data.
  • Deploy failures: check the “Verify API Token” step output and environment secret names (see mismatch flag above) before anything else.

Project vault

Cloudflare Access authorization and your passphrase are required to retrieve and decrypt stored values.

Client-Side Encrypted Secret Vault

Zero-knowledge architecture. Secrets are encrypted client-side using Web Crypto AES-256-GCM before leaving this browser tab. Edge databases store only ciphertext, IV, and salt.

Encrypted Records for baghbaan (0)

Encrypted records have not been loaded.

Add / Rotate Encrypted Secret