soleprint/station/monitors/databrowse/README.md

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

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

Or with uvicorn:

uvicorn ward.monitor.data_browse.main:app --port 12020 --reload

Environment Variables

# 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:

{
  "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:

"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:

{
  "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