PeriShift

PeriShift is a coordination platform designed to move time-sensitive food donations from donors to organizations that can use them. It brings key details into one workflow: the food and quantity available, its pickup window and deadline, recipient demand, and rider capacity. The planned workflow matches donations with recipients and riders using a deterministic, feasibility-first planner. It checks constraints such as deadlines, capacity, receiving windows, and handling needs before ranking possible handoffs. Donors and recipients can confirm offers, riders can accept pickup assignments, and the system can record pickup and receipt. If a rider becomes unavailable, a destination closes, or a deadline is at risk, coordinators can review the issue and consider another feasible option. Architecture: PeriShift is designed as a modular monolith. A React and TypeScript web app communicates with a Python FastAPI backend through REST APIs. The backend uses Pydantic for request and data validation, and PostgreSQL as the durable source of truth for donations, quantities, assignments, and custody events. SQLAlchemy and Alembic support database access and schema changes. A background worker is planned for asynchronous tasks, while persisted events and Server-Sent Events (SSE) are planned to deliver live updates to the web app. Routing is intended to use a deterministic provider, with Leaflet as the planned map interface. The design emphasizes traceable quantities and custody records, while keeping risk alerts separate from custody history. PeriShift supports human coordination; it does not replace food-safety checks or guarantee delivery. The repository currently contains the landing page and early API, database, and data-contract foundations. The full logistics workflow is still under development.