AGENTS.md – Contributor & Agent Guide for Arivu Supply Chain System
Overview
This repository implements a modular, FastAPI-based supply chain system for Arivu Foods, allowing distributors and retailers to manage inventory, orders, and authentication. Agents and contributors should focus on modular design, clean API boundaries, and security.
Key Modules
supply_chain_system/inventory/ – Inventory CRUD APIs
supply_chain_system/auth/ – Auth + JWT token issuance
supply_chain_system/database/ – SQLAlchemy setup and models
main.py – FastAPI app entry point, router registration
Development Environment
Activate virtual env: source arivu-venv/bin/activate
Install dependencies: pip install -r requirements.txt
Run server (dev): uvicorn supply_chain_system.main:app --reload
Run server (prod): gunicorn -w 4 -k uvicorn.workers.UvicornWorker supply_chain_system.main:app
Access docs: http://localhost:8000/docs
Testing & Validation
Add logic tests under tests/ directory (planned)
Verify routes using Swagger UI or curl
Run endpoint with token:
curl -H "Authorization: Bearer <token>" http://localhost:8000/inventory/
Lint checks (optional): flake8 supply_chain_system/
Roles & Access
Distributor (was 'admin') – Full access to inventory endpoints
Retailer – Read-only inventory access
Use Depends(get_current_user) for auth dependency. Check roles like:
if current_user.role != "distributor": raise HTTPException(403)
How Agents Should Work
Look for AGENTS.md in subfolders to scope tasks
Read routes.py in each module to discover public API
Inspect models.py for data relationships
Follow naming and Pydantic schema conventions from existing code
PR Instructions
Title format: [<module>] <change summary>
Include updated tests (if applicable)
Ensure all imports are scoped and DB sessions closed
Document all new endpoints in OpenAPI auto-docs (FastAPI will handle if annotated properly)
Prompting & Codex Tips
Refer to specific files (e.g., inventory/routes.py, auth/schemas.py)
Include exact models (like InventoryItem) in instructions
Provide steps to reproduce if describing a bug
Break down large tasks into multi-step subtasks if possible
Use this file as a config + context base for contributor agents
Migration Targets (WIP)
Migrate frontend/ to consume /inventory/ and /auth/
Introduce orders/ module with similar CRUD scaffolding
Add real-time notification system (via WebSocket or async tasks)
Summary
This project uses FastAPI + SQLAlchemy in a modular service architecture. Follow this AGENTS.md as shared context for agents and human contributors to maintain clarity, clean PRs, and secure scalable APIs.