feat: Add Emergency Calls Service with Complete API and Analytics

[dvalenca]

📋 Summary
Implements a comprehensive emergency calls service for SAMU data analysis, including database schema, API endpoints, analytics, and full test coverage.

🚀 Features Added
🗄️ Database & Schema
New emergency_calls table with 103k+ records from SAMU data

Comprehensive schema with fields for accidents, demographics, and locations

Automated data seeding from TSV file with proper type conversions

Database validation queries for data quality assurance

🔌 RESTful API
Calls endpoints: List, filter, and retrieve individual emergency calls

Analytics endpoints: Municipality stats, accident types, gender distribution, dangerous streets

Full pagination, filtering, and sorting support

OpenAPI documentation with interactive interface

📊 Analytics Features
Municipality-based emergency call statistics

Accident type distribution analysis

Gender and age demographic breakdowns

Most dangerous streets identification

Temporal analysis capabilities

🧪 Testing & Quality
Comprehensive test suite covering all endpoints

Database integration tests with proper isolation

Error handling and edge case validation

Code quality checks (lint, format, type-check)

📁 Files Added
apps/emergency-calls/
├── src/
│ ├── db/ # Database layer
│ ├── routes/ # API endpoints
│ │ ├── calls/ # Emergency calls CRUD
│ │ └── analytics/ # Analytics endpoints
│ ├── lib/ # Shared utilities
│ └── middlewares/ # Request middleware
├── test/ # Test suite
├── Dockerfile # Container setup
└── package.json # Dependencies & scripts

packages/database/
└── src/schemas/emergency-calls/ # Shared database schema

Copy
🛠️ Technical Implementation
Database Schema
Nullable fields for incomplete data handling

Proper indexing for query performance

Zod validation schemas for type safety

Shared schema package for reusability

API Architecture
Route-handler separation pattern

OpenAPI specification generation

Structured error handling

Request/response validation

Data Processing
Batch processing for large datasets (100 records/batch)

Type conversion handling (strings → integers, dates)

Null value management for incomplete records

Performance optimized queries

📈 API Endpoints
Calls
GET /v1/calls - List calls with filtering

GET /v1/calls/{id} - Get specific call details

Analytics
GET /v1/analytics/municipalities - Municipality statistics

GET /v1/analytics/accident-types - Accident type distribution

GET /v1/analytics/gender-distribution - Gender demographics

GET /v1/analytics/dangerous-streets - Most dangerous locations

🔧 Commands

Development

pnpm --filter @atlas/emergency-calls dev

Database

pnpm --filter @atlas/emergency-calls db:seed

Testing

pnpm --filter @atlas/emergency-calls test

Documentation

pnpm --filter @atlas/emergency-calls generate-openapi

Copy
bash
📚 Documentation
Complete API documentation at /docs/?api=emergency-calls-api

Database validation queries included

Comprehensive README with usage examples

Updated manual database setup guide

✅ Quality Assurance
All tests passing

Code quality checks passed

OpenAPI specification generated

Database properly seeded and validated

CI/CD integration ready

Ready for review and deployment 🚀