# tracking_kits - Architecture

**Date:** 2026-03-13
**Application Type:** Single-part Classic ASP web application

## Executive Summary

`tracking_kits` is a server-rendered IIS application that manages operational workflows around election mail pieces. It combines browser-driven CRUD screens with file-system side effects and batch automation. The architecture is straightforward but environment-sensitive: controllers render views and call repositories, while proofs, inkjet exports, and tracking exports rely on COM libraries, report templates, and Windows file shares.

## Runtime Flow

1. IIS serves [../index.asp](../index.asp).
2. `index.asp` redirects to [../App/Controllers/Home/HomeController.asp](../App/Controllers/Home/HomeController.asp).
3. The controller includes [../App/include_all.asp](../App/include_all.asp), which loads the MVC framework, DAL, app config, and all repositories.
4. `Routes.Initialize "/App/"` from [../App/app.config.asp](../App/app.config.asp) establishes route resolution for controller files under `App/`.
5. Controller actions populate view-model objects and include `.asp` view templates.
6. Repositories issue SQL through `DAL.Query`, `DAL.Execute`, and `DAL.PagedQuery`.
7. Some controller actions and automation scripts create files, call report engines, and move outputs into export directories.

## Major Architectural Pieces

### Presentation Layer

- Controller classes live under `App/Controllers/*`.
- Views live under `App/Views/*`.
- View-model types live under `App/ViewModels/*`.
- Shared layout fragments live in `App/Views/Shared/`.

This layer is synchronous and page-oriented. There is no client-side SPA architecture in the codebase.

### Application/Workflow Layer

Controller actions contain most orchestration logic. Key examples:

- `HomeController.CreateKit` and `HomeController.Search` drive jurisdiction lookup for kit creation.
- `KitController.SwitchBoardIndex` and `SwitchBoardPurpleEnvelopsIndex` drive operational dashboards.
- `KitController.ExportTrackingLabels` renders a report to PDF and moves it into an export folder.
- `KitController.ExportSnailWorksTracking` writes CSV exports from repository-provided data.
- Purple-envelope color assignment logic is handled directly in controller POST actions.

### Persistence Layer

- ADO access is centralized in `App/DAL/lib.DAL.asp`.
- Repositories under `App/DomainModels/` contain raw SQL and map records into model classes.
- Pagination and search are implemented inside repositories rather than a service layer.
- The database appears to be an Access MDB with migrations tracked in `Data/Migrations`.

### Shared Framework Layer

The `MVC/` directory provides reusable infrastructure:

- `lib.MVC.asp` and `lib.Routes.asp` for dispatch/routing
- `lib.Automapper.asp` for record/form mapping
- `lib.HTMLSecurity.asp` for anti-CSRF helpers
- `lib.Flash.asp`, `lib.FormCache.asp`, `lib.Helpers.asp`, `lib.Collections.asp`, and related helpers

This shared code is effectively the application's internal framework.

### Batch / Integration Layer

- `ImportService/TrackingDataImport.vbs` handles import/export/proof workflows outside HTTP requests.
- PowerShell and VBScript utilities exist for address updates, service installation, and batch processing.
- COM libraries provide CSV, SFTP, report, and PDF functionality.

## Data Architecture

The schema is migration-driven. Core tables inferred from migrations and repositories:

- `Jurisdiction`
- `Contact`
- `Settings`
- `Kit`
- `Kit_Labels` / `KitLabels`
- `InkJetRecords`
- `CustomOfficeCopyJob`
- `Colors`

Relationships are implied through foreign-key migrations and repository joins, especially around kits, labels, inkjet records, contacts, and jurisdictions.

## Route / Action Design

This app exposes controller-action routes rather than a versioned API. The practical contract surface is:

- User-facing pages under `Home`, `Kit`, `Jurisdiction`, `Contacts`, `Settings`, `InkjetRecords`, and `CustomOfficeCopyJob`
- Form POST actions guarded by anti-CSRF tokens
- Operational actions that change status and produce files

There is no evidence of JSON APIs being a primary integration mechanism.

## External Dependencies and Constraints

### Windows / IIS

- Runtime assumes IIS + Classic ASP.
- Paths in config and scripts reference drive letters and UNC shares.
- End-to-end behavior depends on Windows COM registration.

### COM / ActiveX

- ReportMan for report rendering
- Debenu PDF Library for PDF operations
- Chilkat libraries for unlockable COM features and SFTP/CSV support

### File-System Coupling

- Export folders are created on demand.
- Existing files may be deleted and replaced.
- Generated artifacts move between local app paths and shared export directories.

## Security and Operational Risks

- Environment-specific values and secrets are embedded in code/config scripts today.
- File-system writes and network share access are central to the workflow and are hard to test in isolation.
- Business logic is distributed across controllers and external scripts, so changes often require cross-file tracing.

## Testing Strategy

- Helper/framework tests exist through ASPUnit.
- There is little evidence of automated coverage for end-to-end kit/proof/export workflows.
- High-confidence changes in controller/export logic will require manual IIS-based verification on Windows.

## Change Guidance

- For UI flow changes, inspect the controller, view model, view, and repository together.
- For export/proof changes, inspect both web controllers and `ImportService/TrackingDataImport.vbs`.
- For schema changes, add a migration under `Data/Migrations` and update the affected repository/model classes.
- For environment changes, audit `App/app.config.asp`, import scripts, and any hard-coded paths or COM usage.

---

_Generated for brownfield analysis._