Skip to content

context.md

Latest commit

 

History

History
164 lines (119 loc) · 4.68 KB

context.md

File metadata and controls

164 lines (119 loc) · 4.68 KB

Boxmatch Context (Project Analysis + Constraints)

1) What this project is

Boxmatch is a Flutter-first surplus food matching platform for exhibition scenarios.

  • Enterprise can post leftover food/drinks.
  • Recipients can reserve and complete pickup with a 4-digit code.
  • Backend is Node.js API deployed on Render.
  • Data is stored in Firebase Firestore, with Spark-plan-friendly architecture.

2) Important clarification on requested files

You asked to include analysis for vite.config.ts and src/ core components.

Current repository status:

  • vite.config.ts: not found in this repo.
  • src/: not found in this repo.
  • Main app code is under Flutter structure lib/.

So this context documents the actual structure that exists now.

3) Current high-level architecture

Frontend (Flutter)

  • Root app bootstrap and routing:

    • lib/main.dart
    • lib/app/app.dart
    • lib/app/app_bootstrap.dart
    • lib/app/app_router.dart
    • lib/core/layout/app_shell.dart

  • Feature modules:

    • lib/features/surplus/presentation/*
    • lib/features/surplus/data/*
    • lib/features/surplus/domain/*

  • Key runtime behavior:

    • Firebase init attempted first.
    • If Firebase unavailable, app falls back to InMemorySurplusRepository for local demo mode.

Backend (Node API)

  • API service:

    • server/index.js
    • server/package.json

  • Core endpoints:

    • GET /health
    • POST /enterprise/listings/create
    • POST /enterprise/listings/:listingId/update
    • POST /enterprise/listings/:listingId/validate-token
    • POST /enterprise/listings/:listingId/rotate-token
    • POST /enterprise/listings/:listingId/revoke-token
    • POST /enterprise/listings/:listingId/reservations
    • POST /recipient/listings/:listingId/reserve
    • POST /enterprise/listings/:listingId/confirm-pickup

Infrastructure and deployment

  • Render blueprint/service definition:
    • render.yaml

Current render.yaml highlights:

  • rootDir: server
  • buildCommand: npm ci
  • startCommand: npm start
  • healthCheckPath: /health
  • autoDeploy: true

Environment variables expected by backend:

  • FIREBASE_PROJECT_ID
  • FIREBASE_CLIENT_EMAIL
  • FIREBASE_PRIVATE_KEY
  • Optional: ENABLE_KPI_EVENT_LOGS

4) Data model (Firestore)

Main collections in active use:

  • venues
  • listings
  • reservations
  • abuse_signals
  • idempotency_keys
  • kpi_daily
  • kpi_summary
  • Optional: kpi_events (if enabled)

5) Existing docs and runbooks

  • Product/readme baseline:
    • README.md
  • Ops docs:
    • docs/ops/environment-matrix.md
    • docs/ops/deploy-runbook.md
    • docs/ops/logging-taxonomy.md
    • docs/ops/release-checklist.md
    • docs/ops/smoke-test.md
    • docs/ops/uptime-monitor-setup.md
  • Execution tracking:
    • docs/wiki/30-day-poc-board.md

6) Testing and quality status

Test suites

  • Unit/domain/data/widget tests under test/.
  • Smoke script for live backend validation:
    • scripts/smoke_test.sh

Coverage

  • Coverage generated by flutter test --coverage.
  • Current workflow now enforces threshold in CI:
    • .github/workflows/flutter-ci.yml
  • Gate rule:
    • overall coverage < 80% => CI fail.

7) CI/CD workflows

Current workflows:

  • deploy-render.yml
    • Trigger Render deploy hook on main changes in backend/deploy files.
  • health-probe.yml
    • Scheduled /health probing.
  • release-checklist-gate.yml
    • Manual release gate with checklist inputs.
  • flutter-ci.yml
    • Analyze + tests + coverage threshold enforcement.

8) Known constraints / what cannot be done purely locally

  1. Render runtime behavior cannot be guaranteed by local code edits only.

    • Backend changes must be deployed to Render to validate real behavior.

  2. Spark plan limitations still apply.

    • Firebase Functions/infra requiring Blaze cannot be used without plan upgrade.

  3. Flutter widget test network constraints.

    • HTTP in widget tests is mocked and can return error behavior.
    • Map tile network rendering is not stable/representative in widget tests.

  4. Pilot-day outputs (Day 27-30) need real event data.

    • Without real KPI + incidents, final pilot reports and decision memo remain placeholders.

9) Current risk hotspots

  • Deployed backend may drift from local backend code (version mismatch risk).
  • No server-side automated migration/compat checks for data shape changes.
  • Map/testing behavior differs between local widget tests and real environment.

10) Recommended next actions

  1. Keep flutter-ci.yml required in branch protection.
  2. Add a backend CI smoke job against staging URL before production deploy.
  3. Add a short release note template that records deployed backend commit SHA.
  4. Continue adding high-value tests for enterprise flow edge cases.