Imported from heyibad/the-hifazat-app (AGENTS.md). Install upstream with npx skills add heyibad/the-hifazat-app. Copyright stays with the author.

AGENTS.md

Context file for AI coding agents. Contains only what cannot be inferred from code. When adding new entries — append at the bottom only.

Project: HIFAZAT

A citizen-facing crisis reporting app for Pakistan. Citizens report urban crises (floods, accidents, fires) via text + images in Roman Urdu, Urdu, or English. A team of autonomous AI agents in the backend ingests the report, fetches external signals (weather, traffic), confirms the crisis, allocates mock resources, and pushes notifications to warn nearby citizens, allocated resources — all without human intervention. Its a full-stack mobile app built with a FastAPI Python backend and an Expo React Native frontend with Expo Go , all running in a single monorepo. using OpenAI Agents SDK framework for the autonomous agents in the backend.

Monorepo root: HIFAZAT/

HIFAZAT/
├── agentic-backend/   # FastAPI Python backend (uv managed)
├── app-ui/            # Expo React Native mobile app (npm managed)
├── docker-compose.yml # One-command full-stack start
└── README.md

Tech Stack

Backend — agentic-backend/

Mobile — app-ui/

Agent Architecture

autonomous agents run sequentially in the backend on every citizen report (qyery coming from app): serves via SSE stream at POST /api/v1/chat/ — see agentic-backend/app/api/v1/chat.py

Key Commands

# Backend
cd agentic-backend
uv sync
uv run uvicorn app.main:app --reload --port 8000

# Mobile
cd app-ui
npm install
npm run start   # w=web  a=android  QR=phone

# Full stack
docker compose up --build
docker compose down

Backend Patterns

New model — no migration needed:

# app/models/my_model.py
from app.models.base import UUIDModel
from sqlmodel import Field

class MyModel(UUIDModel, table=True):
    __tablename__ = "my_models"
    name: str = Field(nullable=False)
# Then import in app/models/__init__.py — table auto-creates on restart

New route:

# app/api/v1/my_route.py → register in app/api/v1/__init__.py

Auth guard:

from app.core.security import get_current_user
async def handler(current_user: User = Depends(get_current_user)): ...

DB session:

async def handler(db: AsyncSession = Depends(get_db)): ...

Mobile Patterns

Always import Tailwind-compatible components from @/tw:

import { View, Text, Pressable, TextInput } from "@/tw"; // ✅
import { View, Text } from "react-native"; // ❌ no className support

API URL:

// app-ui/.env
EXPO_PUBLIC_API_URL=http://localhost:8000/api/v1
// Physical device on LAN: http://<PC_IP>:8000/api/v1
// Android emulator: auto-resolves to 10.0.2.2:8000

SSE stream lives in src/services/api.ts → chatService.streamChat() returns a cleanup function. Always call it on unmount.

Never style KeyboardAvoidingView or ScrollView with Tailwind — use the style prop directly.

Critical Rules

• Expo Go only — never use libraries that require expo prebuild, bare workflow, or custom native modules. If a library requires linking, find an Expo Go compatible alternative.
• uv add <package> — never pip install
• Never run alembic — tables are auto-created
• Never use EventSource for SSE — use XMLHttpRequest
• Never commit secrets — use .env files (see .env.example)

External Docs — MUST Use Context7 MCP

Before writing any code that uses a library, you MUST pull its fresh docs via Context7 MCP.

Do not rely on your training data for any library used in this project — versions may have breaking changes and your knowledge may be outdated or wrong.

When to use Context7:

• You are about to use any library and need usage examples
• You are unsure about a specific feature or API of a library
• You are using a newer version of a library you don't have full context on

Examples of when to pull docs:

• Using openai-agents SDK → pull fresh docs first
• Using NativeWind v5 → pull fresh docs first
• Using Expo Router file-based routing → pull fresh docs first
• Using SQLModel async patterns → pull fresh docs first

How: Use the Context7 MCP tool, search the library, read the relevant section, then write the code.

Reference Files

Expo HAS CHANGED

Read the exact versioned docs at https://docs.expo.dev/versions/v55.0.0/ before writing any code.