Social Service Screening Assistant

A comprehensive system for case workers to conduct child abuse screening and reporting with AI assistance.

Features

• Linear Screening Protocol: Step-by-step questionnaire with risk scoring
• Branching Decision Tree: Dynamic reporting workflow based on screening results
• AI Assistance: Ollama-powered guidance based on protocol documents
• Protocol Search (Phase 1): Client-side keyword/BM25 search with citations (Vercel-friendly)
• Document RAG (Future): Retrieval + generation architecture documented in docs/rag-architecture-roadmap.md
• Admin Rule Editor: No-code interface for updating screening rules and decision trees
• Audit Logging: Complete trail of all decisions and actions

Architecture

Frontend (React + TypeScript) → Port 3001
Backend (FastAPI) → Port 8000
Ollama (Local LLM) → Port 11434
Firebase (Hosting) → Cloud
Firestore (Database) → Cloud

Notes:

• Phase 1 protocol search is client-side and does not require the backend to be running.
• The backend is still used for other features and for future RAG generation.

Prerequisites

1. Python 3.10+
2. Node.js 18+
3. Ollama - Install Ollama
4. Firebase CLI (optional for hosting/deploy)

Quick Start

1. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file
cp .env.example .env

# Edit .env with your configuration
# Required: OLLAMA_ENDPOINT, OLLAMA_MODEL

2. Start Ollama

# Pull the model (first time only)
ollama pull llama3.1:latest

# Ollama should be running on http://127.0.0.1:11434
# Verify with: curl http://127.0.0.1:11434/api/tags

3. Process Protocol Documents

Place your PDF documents in the appropriate folders:

• docs/screening/ - Screening protocol PDFs
• docs/reporting/ - Reporting guideline PDFs

Generate the client-side search corpus JSON (Phase 1):

python3 backend/scripts/generate_corpus_simple.py

# Output:
# frontend/public/protocol_corpus.json

Optional (backend-managed documents for future RAG / non-client search):

curl -X POST "http://localhost:8000/api/documents/upload" \
  -F "file=@docs/screening/your_protocol.pdf" \
  -F "document_type=screening_guide" \
  -F "title=Child Abuse Screening Protocol"

4. Start Backend

cd backend
source venv/bin/activate
python -m api.main

# Backend will start on http://localhost:8000
# API docs available at http://localhost:8000/docs

Note: The backend is not required for Phase 1 protocol search, but is required for AI assistance and other API features.

5. Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

# Frontend will start on http://localhost:3001

Protocol Search (Phase 1) will load its index from:

• frontend/public/protocol_corpus.json

Port Configuration

• Frontend: Port 3001 (configured in vite.config.ts)
• Backend: Port 8000 (configured in api/main.py)
• Ollama: Port 11434 (default)

To change ports:

1. Frontend: Edit frontend/vite.config.ts
2. Backend: Edit backend/api/main.py (uvicorn.run port parameter)
3. Update CORS in backend/.env (ALLOWED_ORIGINS)

Database Setup

Persistent storage is planned to use Firestore (Firebase) for production deployments.

Note: Firebase/Firestore integration is not documented here yet. This README will be updated once the data model and auth rules are finalized.

Project Structure

social-service-screening-assistant/
├── backend/
│   ├── api/
│   │   ├── main.py              # FastAPI application
│   │   └── ollama_service.py    # Ollama integration
│   ├── document_processor/
│   │   └── pdf_processor.py     # PDF text extraction
│   ├── vector_store/
│   │   └── faiss_store.py       # FAISS vector database
│   ├── models/
│   │   └── schemas.py           # Pydantic models
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── screening/       # Screening interface
│   │   │   ├── reporting/       # Decision tree UI
│   │   │   ├── admin/           # Rule editor
│   │   │   └── knowledge-base/  # Document viewer
│   │   └── services/
│   │       ├── api.ts           # API client
│   └── package.json
├── docs/
│   ├── screening/               # Your screening PDFs
│   └── reporting/               # Your reporting PDFs
└── data/
    ├── vector_store/            # FAISS index
    └── synthesized_cases/       # Test data

API Endpoints

Screening

• POST /api/screening/questions - Get screening questions
• POST /api/screening/submit - Submit response
• POST /api/screening/ai-assist - Get AI assistance
• POST /api/screening/analyze - Analyze case risk

Decision Tree

• GET /api/decision-tree/start - Get start node
• POST /api/decision-tree/traverse - Navigate tree

Reporting

• POST /api/reporting/submit - Submit report

Documents

• POST /api/documents/upload - Upload PDF
• POST /api/documents/search - Search protocols
• GET /api/documents/stats - Vector store stats

Note: /api/documents/search is currently commented out in the UI in favor of Phase 1 client-side search.

Admin

• GET /api/admin/rules - List rules
• POST /api/admin/rules - Create rule
• PUT /api/admin/rules/{id} - Update rule
• DELETE /api/admin/rules/{id} - Deactivate rule

Development Workflow

Adding New Screening Questions

1. Use admin UI or API to create rule:

{
  "rule_type": "screening_question",
  "rule_data": {
    "question_id": "q8",
    "order": 8,
    "text": "Your question here?",
    "type": "yes_no",
    "risk_score_yes": 5,
    "risk_score_no": 0
  }
}

Updating Decision Tree

1. Access admin UI at /admin/decision-tree
2. Visual editor allows drag-and-drop node creation
3. Set conditions and actions for each node
4. Changes are versioned automatically

Processing New Documents

# Upload via API
curl -X POST "http://localhost:8000/api/documents/upload" \
  -F "file=@path/to/document.pdf" \
  -F "document_type=screening_guide" \
  -F "title=Document Title"

# Or use the admin UI document manager

Testing

Backend Tests

cd backend
pytest tests/

Frontend Tests

cd frontend
npm test

Manual Testing with Synthesized Data

The database seed file includes realistic test cases. Use these for testing workflows.

Security Considerations

⚠️ Important: This system handles sensitive information about children and families.

1. Authentication: Implement proper user authentication (planned via Firebase Auth)
2. Authorization: Implement role-based access control and least-privilege rules (planned via Firestore Security Rules)
3. Audit Logging: All actions are logged with user ID and timestamp
4. Data Encryption: Use HTTPS in production
5. HIPAA Compliance: Consult legal counsel before production deployment
6. Access Control: Limit admin access to authorized personnel only

Deployment

Backend Deployment

• Use Docker for containerization
• Deploy to AWS/GCP/Azure
• Configure environment variables
• Set up SSL/TLS certificates

Frontend Deployment

• Build: npm run build
• Deploy to Vercel/Netlify/Cloudflare Pages
• Configure environment variables

Troubleshooting

Ollama Connection Issues

# Check if Ollama is running
curl http://127.0.0.1:11434/api/tags

# Restart Ollama
ollama serve

Port Already in Use

# Kill process on port 3001
lsof -ti :3001 | xargs kill -9

# Kill process on port 8000
lsof -ti :8000 | xargs kill -9

Vector Store Issues

# Clear and rebuild vector store
curl -X DELETE http://localhost:8000/api/documents/clear
# Then re-upload documents

Contributing

This is a prototype for internal use. For production deployment:

1. Implement Firebase/Firestore persistence (planned)
2. Implement comprehensive testing
3. Add user authentication
4. Conduct security audit
5. Obtain legal/compliance review

License

Internal use only. Not for public distribution.

Support

For questions or issues, contact the development team.

---

Version: 1.0.0
Last Updated: January 2026