StreetLives Conversational Intake System

An empathetic, trauma-informed chatbot that helps people experiencing homelessness find services in NYC.

Project Architecture

NO HALLUCINATION: LLM handles conversation ONLY. All service data comes from database queries.

StreetLives/
├── backend/          # Python FastAPI backend
├── frontend/         # React frontend (to be implemented)
├── services/         # Microservices (future)
├── infra/            # Infrastructure & deployment
└── docs/             # Documentation

Backend (FastAPI + PostgreSQL)

Key Features

• Trauma-informed dialog: Warm, patient, crisis-aware conversation
• Dynamic taxonomy: Service categories loaded from database (39 types)
• Eligibility-driven questions: Asks only what's needed based on service rules
• Progressive disclosure: One question at a time
• Session management: Tracks conversation state
• Privacy by design: Optional sensitive questions, consent required

API Endpoints

# Start conversation
POST /api/chat/start
→ Returns: session_id + greeting

# Send message
POST /api/chat/message
{
  "session_id": "uuid",
  "message": "I need food"
}
→ Returns: empathetic response + extracted data + progress

# Check session status
GET /api/chat/session/{session_id}

Setup

# Install Python dependencies
cd backend
pip install -r requirements.txt

# Set environment variables
cp ../.env.example ../.env
# Edit .env with database credentials

# Run backend
cd backend/api
python main.py

# API docs available at: http://localhost:8000/docs

Environment Variables

Required in .env:

# Database
DB_HOST=your-db-host
DB_PORT=5432
DB_NAME=streetlives
DB_USER=your-user
DB_PASSWORD=your-password

# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

Frontend (React)

Setup (TODO: Not yet implemented)

cd frontend
npm install
npm start

Frontend will connect to backend API at http://localhost:8000

Database Schema

Production PostgreSQL database with:

• 2,414 locations across NYC
• 3,506 services from various providers
• 39 taxonomy categories (Food, Shelter, Clothing, etc.)
• 3,646 eligibility rules (determines what questions to ask)

See backend/DATABASE_SCHEMA_FINDINGS.md for details.

Development Workflow

See CLAUDE.md for complete development log and progress tracking.

Testing Backend

# Test database connection
cd backend/tests
python test_db_connection.py

# Explore database schema
cd backend/scripts
python explore_schema.py

# Run FastAPI server
cd backend/api
python main.py

Visit http://localhost:8000/docs for interactive API documentation.

Architecture Principles

1. NO Hallucination: LLM NEVER generates service data
2. Data-Driven: Questions based on database eligibility rules
3. Trauma-Informed: Empathetic, patient, crisis-aware
4. Privacy First: Consent required, optional sensitive questions
5. Progressive Disclosure: One question at a time
6. Template Queries: Pre-defined, parameterized, auditable

Project Status

✅ Completed:

• Database schema exploration
• Pydantic models aligned with DB
• Dynamic taxonomy loader
• Conversational intake flow logic
• Empathetic dialog service (OpenAI)
• Session management
• FastAPI chat endpoints

⏳ In Progress:

• Query execution engine
• Service card formatter
• Frontend implementation

License

Copyright © 2025 StreetLives

Contact

For questions about this codebase, see CLAUDE.md for development log.