# Data Browse Monitor

**Test-oriented data navigation for AMAR** - quickly find which users to log in as for different test scenarios.

## Purpose

When working on multiple tickets simultaneously, you need to quickly navigate to users in specific data states:
- New user with no data
- User with pets but no requests
- User with pending payment
- Vet with active requests
- Admin account

This monitor provides at-a-glance views of the database grouped by test-relevant states.

## Architecture

Follows pawprint **book/larder pattern**:
- **larder/** contains all data files (schema, views, scenarios)
- **main.py** generates SQL queries from view definitions
- Two modes: **SQL** (direct queries) and **API** (Django backend, placeholder)

### Key Concepts

**Schema** (`larder/schema.json`)
- AMAR data model with SQL table mappings
- Regular fields (from database columns)
- Computed fields (SQL expressions)
- Support for multiple graph generators

**Views** (`larder/views.json`)
- Define what to display and how to group it
- Each view targets an entity (User, PetOwner, Veterinarian, etc.)
- Can group results (e.g., by role, by data state, by availability)
- SQL is generated automatically from view configuration

**Scenarios** (`larder/scenarios.json`)
- Test scenarios emerge from actual usage
- Format defined, real scenarios added as needed
- Links scenarios to specific views with filters

## Available Views

1. **users_by_role** - All users grouped by USER/VET/ADMIN for quick login selection
2. **petowners_by_state** - Pet owners grouped by data state (has_pets, has_coverage, has_requests, has_turnos)
3. **vets_by_availability** - Vets grouped by availability status (available, busy, very busy, no availability)
4. **requests_pipeline** - Active service requests grouped by state (similar to turnos monitor)

## Running Locally

```bash
cd /home/mariano/wdir/ama/pawprint/ward/monitor/data_browse
python main.py
# Opens on http://localhost:12020
```

Or with uvicorn:
```bash
uvicorn ward.monitor.data_browse.main:app --port 12020 --reload
```

## Environment Variables

```bash
# Database connection (defaults to local dev)
export NEST_NAME=local
export DB_HOST=localhost
export DB_PORT=5433
export DB_NAME=amarback
export DB_USER=mariano
export DB_PASSWORD=""
```

## API Endpoints

```
GET  /                         # Landing page
GET  /view/{view_slug}         # View display (HTML)
GET  /health                   # Health check
GET  /api/views                # List all views (JSON)
GET  /api/view/{view_slug}     # View data (JSON)
GET  /api/schema               # Data model schema (JSON)
GET  /api/scenarios            # Test scenarios (JSON)
```

## Adding New Views

Edit `larder/views.json`:

```json
{
  "name": "my_new_view",
  "title": "My New View",
  "slug": "my-new-view",
  "description": "Description of what this shows",
  "mode": "sql",
  "entity": "PetOwner",
  "group_by": "some_field",
  "fields": ["id", "first_name", "last_name", "email"],
  "display_fields": {
    "id": {"label": "ID", "width": "60px"},
    "first_name": {"label": "Name", "width": "120px"}
  }
}
```

The SQL query is automatically generated from:
- Entity definition in `schema.json` (table name, columns)
- Fields list (regular + computed fields)
- Group by configuration (if specified)
- Filters (if specified)

## Adding Computed Fields

Edit `larder/schema.json` in the entity definition:

```json
"computed": {
  "has_pets": {
    "description": "Has at least one pet",
    "sql": "EXISTS (SELECT 1 FROM mascotas_pet WHERE petowner_id = mascotas_petowner.id AND deleted = false)"
  }
}
```

Computed fields can be used in views just like regular fields.

## Adding Test Scenarios

As you identify test patterns, add them to `larder/scenarios.json`:

```json
{
  "name": "User with Pending Payment",
  "slug": "user-pending-payment",
  "description": "User with accepted request awaiting payment",
  "role": "USER",
  "entity": "ServiceRequest",
  "view": "requests_pipeline",
  "filters": {
    "state": ["vet_accepted", "in_progress_pay"],
    "has_payment": false
  },
  "test_cases": [
    "Payment flow (MercadoPago)",
    "Payment reminders",
    "Payment timeout"
  ]
}
```

## Files

```
data_browse/
├── larder/
│   ├── .larder              # Larder marker (book pattern)
│   ├── schema.json          # AMAR data model with SQL mappings
│   ├── views.json           # View configurations
│   └── scenarios.json       # Test scenarios
├── main.py                  # FastAPI app
├── index.html               # Landing page
├── view.html                # View display template
└── README.md                # This file
```

## Status

**Current:** SQL mode fully implemented, ready for local testing
**Next:** Test with local database, refine views based on usage
**Future:** See `workbench/data_browse_roadmap.md`