# tracking_kits - Route and Integration Contracts

**Date:** 2026-03-13

## Important Note

This project does not expose a conventional JSON REST API. Its primary contract surface is a set of Classic ASP controller routes that render HTML pages and process form submissions. In addition, it has file-based export/import interfaces used by batch automation.

## Web Route Surface

Routing is initialized by [../App/app.config.asp](../App/app.config.asp), and requests are dispatched from controller ASP files under `App/Controllers`.

### HomeController

- `Index`
  - Purpose: render the switchboard/home screen
- `CreateKit`
  - Purpose: list jurisdictions with pagination for kit creation
- `Search`
  - Purpose: search jurisdictions by `JCode`, `Name`, address fields, and IMB values
- `Print`
  - Purpose: render a sample/report PDF using `Label_Report.rep`

### KitController

- `Index`
  - Purpose: paged list of kits
- `Search`
  - Purpose: search kits by `ID`, `JobNumber`, and `JCode`
- `SwitchBoardIndex`
  - Purpose: operational list for label-based kits
- `SwitchBoardEdit`
  - Purpose: edit/view a single kit switchboard entry
- `SwitchBoardPurpleEnvelopsIndex`
  - Purpose: list purple-envelope kits
- `SwitchBoardPurpleEnvelopeEdit`
  - Purpose: edit purple-envelope kit details, color options, and precinct color data
- `SwitchBoardPurpleEnvelopeEditPost`
  - Purpose: update purple-envelope form fields and status
- `AssignKitColorPost`
  - Purpose: assign a color to all labels/records in a kit
- `AssignPrecinctColorsPost`
  - Purpose: assign colors at the precinct level
- `ExportTrackingLabels(id)`
  - Purpose: generate and move a kit label PDF
- `ExportSnailWorksTracking(id)`
  - Purpose: generate SnailWorks CSV export data

### Other Controllers

The repository structure implies standard CRUD routes for:

- `JurisdictionController`
- `ContactsController`
- `InkjetRecordsController`
- `SettingsController`
- `CustomOfficeCopyJobController`
- `KitLabelsController`

These are primarily view-rendering and form-post endpoints.

## Form / POST Contracts

Observed POST patterns:

- Classic HTML forms
- anti-CSRF tokens managed by `HTMLSecurity.SetAntiCSRFToken`
- redirect-on-success flow with flash messaging
- model hydration via `Automapper.AutoMap(Request.Form, model)`

## File-Based Integration Contracts

### Tracking Label PDF Export

- Triggered from kit workflows
- Uses `Data/Label_Report.rep`
- Writes PDF output to app-local `Data/` temporarily
- Moves final artifact into `ExportDirectory\<Jurisdiction>\...`

### SnailWorks Export

- Generates CSV files per kit
- Includes a header section plus detail records
- Output path depends on configured `ExportDirectory`

### Inkjet Export / Proof / Import Processing

- `ImportService/TrackingDataImport.vbs` performs status-driven processing
- Outputs CSV and PDF artifacts
- Reads and writes from configured directories and network shares
- Uses COM-based CSV/report/SFTP functionality

## Security and Validation Notes

- CSRF checks are present for important form posts.
- Input validation exists unevenly; some validation calls are commented out in controllers.
- There is no API schema enforcement layer; the contract is defined by forms, SQL expectations, and downstream file formats.

## Change Guidance

- Treat controller action names, form field names, status strings, and export file names as part of the operational contract.
- Before changing an export format, inspect both web controllers and import-service scripts.
- Before changing a status value, search for every status-dependent branch in both `App/` and `ImportService/`.

---

_Generated for brownfield analysis._
