# Canteen Seed Import — Agent Guide

Standalone seed data import tool for populating the Canteen assets database from Cantaloupe CSV exports. Conceptual prototype before integration into admin panel.

## Stack

- **Python** 3.11+, **pandas**, **numpy**, **sqlite-utils**
- **httpx** — sync to remote DB targets
- **rich** — CLI output formatting
- **click** — CLI framework
- **FastAPI** + **uvicorn** — web UI for import workflow
- **python-multipart** — file upload

## Project Structure

```
main.py                   # CLI entry point (seed/update modes)
parser.py                 # CSV/Excel parsing, header mapping, location extraction
db_writer.py              # SQLite write operations
sync.py                   # Sync to remote DB targets
backup.py                 # Backup/restore GPS + photo data
reporter.py               # Validation report generation
requirements.txt
start.sh                  # Production launch (port 8091)
start-dev.sh              # Dev launch (port 8093, separate dev DB)

seed-data/
  import_seed.csv         # Main import CSV
  headers_modified.csv    # Header mapping reference
  reference_handbook.md   # Extraction rules
  validation_report.md    # Validation results

web/
  server.py               # FastAPI web UX
  static/
    index.html            # Import web UI
```

## How to Run

```bash
# CLI seed import
python main.py seed-data/import_seed.csv --db /path/to/assets.db

# CLI update mode (incremental)
python main.py seed-data/import_seed.csv --mode update --db /path/to/assets.db

# Web UI (production)
./start.sh

# Web UI (dev)
./start-dev.sh
```

## Key Architecture

- **Two modes:** `seed` (fresh insert) and `update` (incremental — skips existing)
- **Dry-run support:** preview changes before committing
- **Backup-preserving** — creates DB backups before imports
- Web UI provides: Excel upload, preview, import, backup management, report viewing
- GPS location derivation from address/city/state columns

## Production

- **Port:** 8091 (prod), 8093 (dev)
- **Configurable via:** `CANTEEN_IMPORT_PORT` env var
- **No systemd**

## Environment Variables

| Var | Default | Description |
|-----|---------|-------------|
| CANTEEN_IMPORT_PORT | 8091 | Web UI port |
| CANTEEN_DB_PATH | — | Target DB path for sync mode |

## Pitfalls

- Seed data CSVs use custom header format — `parser.py` has header mapping logic
- Location extraction is heuristic (address/columns → GPS lookup)
- Web UI and CLI share the same parser/db_writer modules