tracking_kits/docs/architecture.md

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.
2. index.asp redirects to ../App/Controllers/Home/HomeController.asp.
3. The controller includes ../App/include_all.asp, which loads the MVC framework, DAL, app config, and all repositories.
4. Routes.Initialize "/App/" from ../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.