Building NourishNet: A Serverless Food-Redistribution Platform with AWS and Kiro
NourishNet is a serverless food-redistribution platform built using AWS and Kiro to reduce food waste and help communities access surplus food. The platform connects restaurants, individuals, and organizations with people or NGOs who need food. Using AWS serverless services, NourishNet provides a scalable, cost-effective, and reliable solution for food listing, matching, notifications, and distribution while supporting a more sustainable and socially responsible future.
Repository: https://github.com/scha54/NourishNet
Food waste and food insecurity are two sides of the same problem. NourishNet is an open-source platform that connects surplus-food donors — restaurants, farms, supermarkets, and individuals — with verified community organizations and the volunteers who move food between them, so that usable food reaches people instead of landfill. Every kilogram redirected is tracked and reported as measurable social impact: meals served and carbon emissions avoided.
This article walks through how NourishNet is architected on AWS, and how it was built using Kiro's spec-driven development workflow.
The Four-Role Workflow
NourishNet models four user roles — Donor, Organization, Volunteer, and Admin — and a single redistribution lifecycle: a donor creates a listing; a verified organization claims it; a volunteer coordinates pickup and delivery; the organization confirms receipt; and impact is recorded. Listings move through an explicit state machine:
draft → available → claimed → in_transit → completed | cancelled | expired.Architecture on AWS
NourishNet is fully serverless, delivered as a TypeScript monorepo with three workspaces: a React frontend, a Lambda backend, and AWS CDK infrastructure.
Frontend — React + AWS Amplify Hosting. A Vite-built React SPA is served through Amplify Hosting over HTTPS, with an SPA rewrite rule so client-side routes resolve correctly. The app uses TanStack Query for server state and injects configuration (API URL, Cognito IDs) at build time via Vite environment variables sourced from stack outputs.
Authentication — Amazon Cognito. A Cognito User Pool manages identity, with four groups mapping to the four roles. The app client is a public client with no secret, and tokens live in memory on the frontend rather than browser storage.
API — Amazon API Gateway (HTTP API). All routes are versioned under
/v1/. A Cognito JWT authorizer protects every route except the public GET /v1/health, enforcing authentication at the gateway before any Lambda executes. Handlers derive role from validated JWT claims, never from request input.Compute — AWS Lambda (Node.js 20). Each function has its own least-privilege IAM role scoped to exact DynamoDB actions and resource ARNs — no wildcards. The backend is strictly layered:
handlers/ (entry points), domain/ (pure business logic, no AWS SDK), repositories/ (all DynamoDB access), and validation/ (shared Zod schemas). Every response uses one envelope: { data } on success, { error: { code, message } } on failure.Data — Amazon DynamoDB single-table design. All entities (USER, DONATION, PICKUP, REPORT) live in one table with a composite
PK/SK and two GSIs, differentiated by key prefixes. Access is driven by a fixed set of documented access patterns; scans are forbidden, keeping the access surface bounded and queries single-round-trip.Observability — Amazon CloudWatch. Each Lambda writes structured JSON logs (never PII) to a dedicated log group with 30-day retention. A dashboard tracks invocations, errors, and p99 latency, and an alarm fires when the combined error rate exceeds 5% over five minutes.
Social impact. Every completed redistribution writes a REPORT record whose meals-equivalent and carbon-saved metrics are computed at write time from centralized constants — turning operational data into credible, reportable impact.
How Kiro Shaped the Build
NourishNet was built with Kiro using its full spec-driven workflow, and the repository itself is the best illustration of the approach.
Specs. The platform is decomposed into six specs under
.kiro/specs/ — foundation, donations, matching, pickup, impact, and moderation — each carrying its own requirements, design, and task list. Features start as structured requirements that drive a technical design and an actionable implementation plan, rather than ad-hoc coding.Steering. Six always-on steering documents encode the project's standards so every interaction stays aligned:
architecture.md (the DynamoDB access patterns and layer-separation rules), security.md (least-privilege IAM, token handling, input sanitization), coding-standards.md, testing.md, product.md, and social-impact.md (the impact measurement model and formulas). These are the guardrails that keep generated code consistent with the system's intent.Agents. Four custom agents bring focused review expertise: a
serverless-architect that audits Lambda/API Gateway/DynamoDB decisions against the documented access patterns, a product-reviewer that checks features against the social mission and four-role model, a property-test-engineer for fast-check property-based tests, and a social-impact-reviewer that verifies impact fields and derived metrics.Hooks. Agent hooks automate quality gates on IDE events — an
api-contract-guard that checks handlers conform to the response envelope, a security-review hook that flags hardcoded secrets or broad IAM, an impact-data-integrity check on repository writes, plus hooks that run backend and property-based test suites.Testing for Correctness
Beyond example-based unit and integration tests, NourishNet uses property-based testing with fast-check for pure domain logic — response-envelope round-trips, DynamoDB key builders, the listing state machine, and the impact calculations — asserting invariants across hundreds of generated inputs rather than a handful of hand-picked cases.
Closing
NourishNet shows how a serverless AWS architecture and Kiro's spec-driven workflow reinforce each other: documented requirements, steering, and reviewing agents produce infrastructure and code that are consistent, secure, and measurable by design. Explore the full source, specs, and steering files at https://github.com/scha54/NourishNet .
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article