# tracking_kits - Module Map

**Date:** 2026-03-13

This guide is the shortest path into the codebase when you need to change a specific feature area. It is organized by module and operational workflow rather than by folder alone.

## Fastest Starting Points

If you need to make a change, start here first:

- **Kit creation / label workflows:** [../App/Controllers/Kit/KitController.asp](../App/Controllers/Kit/KitController.asp)
- **Jurisdiction search / import:** [../App/Controllers/Jurisdiction/JurisdictionController.asp](../App/Controllers/Jurisdiction/JurisdictionController.asp)
- **Proof/export behavior:** [../App/Controllers/Kit/KitController.asp](../App/Controllers/Kit/KitController.asp) and [../ImportService/TrackingDataImport.vbs](../ImportService/TrackingDataImport.vbs)
- **Inkjet / color assignment:** [../App/Controllers/Kit/KitController.asp](../App/Controllers/Kit/KitController.asp) and [../App/DomainModels/InkjetRecordsRepository.asp](../App/DomainModels/InkjetRecordsRepository.asp)
- **Database/schema behavior:** [../Data/Migrations](../Data/Migrations) and the matching repository under [../App/DomainModels](../App/DomainModels)

## 1. Kit Module

### What it owns

- creating tracking kits
- creating label records for a kit
- operational switchboard screens
- purple-envelope workflows
- SnailWorks export
- label PDF export
- status transitions on kits

### Main files

- [../App/Controllers/Kit/KitController.asp](../App/Controllers/Kit/KitController.asp)
- [../App/DomainModels/KitRepository.asp](../App/DomainModels/KitRepository.asp)
- [../App/DomainModels/KitLabelsRepository.asp](../App/DomainModels/KitLabelsRepository.asp)
- [../App/DomainModels/SnailWorksRepository.asp](../App/DomainModels/SnailWorksRepository.asp)
- [../App/Views/Kit/CreateTrackingKit.asp](../App/Views/Kit/CreateTrackingKit.asp)
- [../App/Views/Kit/SwitchBoardIndex.asp](../App/Views/Kit/SwitchBoardIndex.asp)
- [../App/Views/Kit/SwitchBoardEdit.asp](../App/Views/Kit/SwitchBoardEdit.asp)
- [../App/Views/Kit/SwitchBoardPurpleEnvelopeEdit.asp](../App/Views/Kit/SwitchBoardPurpleEnvelopeEdit.asp)

### Read order

1. `KitController.CreateTrackingKit` / `CreatePost` / `CreateTrackingKitPost`
2. `KitRepository.AddNew`
3. `KitLabelsRepository.BulkAdd`
4. `ExportTrackingLabels` and `ExportSnailWorksTracking`
5. matching view template

### Important coupling

- `CreatePost` creates a kit, bulk-creates labels, then immediately generates export artifacts.
- `CreateTrackingKitPost` creates the kit and labels but does not call the export methods.
- `SwitchBoardEdit` is the main inspection screen for label-based kits.
- `SwitchBoardPurpleEnvelopeEdit` combines kit data, STID choices, color lists, and precinct-level color data in one page model.
- Purple-envelope color changes are persisted through `InkjetRecordsRepository`, not `KitRepository`.

### Hotspots to treat carefully

- status strings such as `Ready to Assign Labels` and `Ready To Assign STIDS`
- export filenames and folder structure
- any change to `JobType`, `OutboundSTID`, `InboundSTID`, or `OfficeCopiesAmount`
- label creation count and bulk-add behavior

## 2. Jurisdiction Module

### What it owns

- jurisdiction CRUD
- jurisdiction search
- jurisdiction-linked contact display
- jurisdiction file import
- entry path into kit creation

### Main files

- [../App/Controllers/Jurisdiction/JurisdictionController.asp](../App/Controllers/Jurisdiction/JurisdictionController.asp)
- [../App/DomainModels/JurisdictionRepository.asp](../App/DomainModels/JurisdictionRepository.asp)
- [../App/DomainModels/ContactsRepository.asp](../App/DomainModels/ContactsRepository.asp)
- [../App/Views/Jurisdiction/index.asp](../App/Views/Jurisdiction/index.asp)
- [../App/Views/Jurisdiction/edit.asp](../App/Views/Jurisdiction/edit.asp)
- [../App/Views/Jurisdiction/import.asp](../App/Views/Jurisdiction/import.asp)
- [../App/Views/Home/CreateTrackingKit.asp](../App/Views/Home/CreateTrackingKit.asp)

### Read order

1. `JurisdictionController.Index` / `Search`
2. `JurisdictionRepository.FindPaged` / `SearchTablePaged`
3. `JurisdictionController.ImportPost` if the change involves file import
4. related edit/create views

### Important coupling

- Search fields are hard-coded in both `HomeController.Search` and `JurisdictionController.Search`.
- `JurisdictionController.Edit` also loads related contacts.
- `ImportPost` is one of the denser controller methods in the app: it handles file upload validation, file rewrite, Jet text-driver parsing, SQL projection, and then persistence/import behavior.
- The kit-creation chooser in the Home area links into `KitController.createTrackingKit` by `JCode`.

### Hotspots to treat carefully

- import file format assumptions: accepted extensions, header handling, tab-vs-delimited mode
- SQL expressions that derive `JCODE`, `Name`, `CSZ`, and `IMB_Digits`
- any field rename touching both repository SQL and import mapping

## 3. Inkjet / Purple Envelope Module

### What it owns

- inkjet record CRUD
- precinct-level data for purple-envelope jobs
- color assignment per kit or precinct

### Main files

- [../App/Controllers/InkjetRecords/InkjetRecordsController.asp](../App/Controllers/InkjetRecords/InkjetRecordsController.asp)
- [../App/DomainModels/InkjetRecordsRepository.asp](../App/DomainModels/InkjetRecordsRepository.asp)
- [../App/Views/Kit/SwitchBoardPurpleEnvelopeEdit.asp](../App/Views/Kit/SwitchBoardPurpleEnvelopeEdit.asp)
- [../App/DomainModels/ColorsRepository.asp](../App/DomainModels/ColorsRepository.asp)

### Read order

1. `KitController.SwitchBoardPurpleEnvelopeEdit`
2. `InkjetRecordsRepository.GetDistinctPrecinctsByKitId`
3. `AssignKitColorPost` / `AssignPrecinctColorsPost`
4. `InkjetRecordsRepository.UpdateColorForKit` / `UpdateColorForPrecinct`

### Important coupling

- purple-envelope UI reads colors and precinct data live in the view
- current color names are resolved inside the template using `ColorsRepository.FindByID`
- the kit edit flow and the precinct color flow share the same screen but use separate forms and anti-CSRF tokens

### Hotspots to treat carefully

- precinct key naming convention: `PrecinctColor_<PRECINCT>`
- `ColorId` propagation rules
- query performance if precinct count grows, because the view performs color lookups during rendering

## 4. Export / Proof Module

### What it owns

- label PDF generation
- SnailWorks CSV export
- report template usage
- file movement into export directories

### Main files

- [../App/Controllers/Kit/KitController.asp](../App/Controllers/Kit/KitController.asp)
- [../App/DomainModels/SnailWorksRepository.asp](../App/DomainModels/SnailWorksRepository.asp)
- [../Data/Label_Report.rep](../Data/Label_Report.rep)
- [../Data/Proofs.rep](../Data/Proofs.rep)
- [../Data/Office-Copy-Proof.rep](../Data/Office-Copy-Proof.rep)
- [../Data/Custom Office Copies Proof.rep](../Data/Custom%20Office%20Copies%20Proof.rep)

### Read order

1. `ExportTrackingLabels`
2. `ExportSnailWorksTracking`
3. `SnailWorksRepository.GetSnailWorksExportById`
4. report template file referenced by the action

### Important coupling

- export methods depend on `ExportDirectory` from [../App/app.config.asp](../App/app.config.asp)
- label PDF generation uses a temporary file in `Data\` before moving it to the final folder
- SnailWorks header values are partially hard-coded inside repository SQL
- SnailWorks detail records join `InkjetRecords`, `KitLabels`, and `Kit`

### Hotspots to treat carefully

- COM object availability and provider connection strings
- jurisdiction-based folder naming
- hard-coded user IDs, emails, and export metadata in `SnailWorksRepository`
- file overwrite/delete behavior before new export generation

## 5. Import Service / Batch Automation Module

### What it owns

- status-driven processing outside the web app
- custom office copy proof generation
- export/import batch processing
- downstream handoff logic such as SFTP and file polling

### Main files

- [../ImportService/TrackingDataImport.vbs](../ImportService/TrackingDataImport.vbs)
- [../InstallService.vbs](../InstallService.vbs)
- [../CiCd](../CiCd)

### What to know before editing

- this script is effectively a second application with its own environment config
- it contains hard-coded path, provider, and external integration behavior separate from `App/app.config.asp`
- the file is encoded differently from most repo files and is harder to inspect casually
- status transitions used here overlap with values set in web controllers

### Hotspots to treat carefully

- any status name change
- any path or folder naming change
- proof/export file naming conventions
- any change to custom office copy jobs

## 6. Shared Framework Module

### What it owns

- routing and dispatch
- HTML helpers and form generation
- anti-CSRF tokens
- automapping of forms and recordsets
- utility collections/helpers used across the app

### Main files

- [../MVC/lib.MVC.asp](../MVC/lib.MVC.asp)
- [../MVC/lib.Routes.asp](../MVC/lib.Routes.asp)
- [../MVC/lib.HTML.asp](../MVC/lib.HTML.asp)
- [../MVC/lib.HTMLSecurity.asp](../MVC/lib.HTMLSecurity.asp)
- [../MVC/lib.Automapper.asp](../MVC/lib.Automapper.asp)
- [../MVC/lib.all.asp](../MVC/lib.all.asp)

### When to open this module

- form helpers render incorrectly
- anti-CSRF handling breaks
- controller dispatch or route generation is wrong
- multiple features fail in the same infrastructural way

## 7. Schema / Data Evolution Module

### What it owns

- database creation and schema changes
- historical meaning of fields added to kits, jurisdictions, and inkjet records

### Main files

- [../Data/Migrations/migrate.asp](../Data/Migrations/migrate.asp)
- [../Data/Migrations/lib.Migrations.asp](../Data/Migrations/lib.Migrations.asp)
- [../Data/Migrations](../Data/Migrations)

### Practical rule

If you add or reinterpret a field in a repository, search migrations first and then search controllers and import scripts for that field name. In this project, schema semantics leak into UI, export logic, and batch automation very quickly.

## Recommended Read Paths By Change Type

### “Add a new field to kit workflow”

Open:
- [../Data/Migrations](../Data/Migrations)
- [../App/DomainModels/KitRepository.asp](../App/DomainModels/KitRepository.asp)
- [../App/ViewModels/KitViewModels.asp](../App/ViewModels/KitViewModels.asp)
- [../App/Controllers/Kit/KitController.asp](../App/Controllers/Kit/KitController.asp)
- [../App/Views/Kit](../App/Views/Kit)

### “Change jurisdiction import behavior”

Open:
- [../App/Controllers/Jurisdiction/JurisdictionController.asp](../App/Controllers/Jurisdiction/JurisdictionController.asp)
- [../App/Views/Jurisdiction/import.asp](../App/Views/Jurisdiction/import.asp)
- [../App/DomainModels/JurisdictionRepository.asp](../App/DomainModels/JurisdictionRepository.asp)

### “Change export file format or proof output”

Open:
- [../App/Controllers/Kit/KitController.asp](../App/Controllers/Kit/KitController.asp)
- [../App/DomainModels/SnailWorksRepository.asp](../App/DomainModels/SnailWorksRepository.asp)
- [../ImportService/TrackingDataImport.vbs](../ImportService/TrackingDataImport.vbs)
- [../Data](../Data)

### “Change purple-envelope or inkjet assignment logic”

Open:
- [../App/Controllers/Kit/KitController.asp](../App/Controllers/Kit/KitController.asp)
- [../App/DomainModels/InkjetRecordsRepository.asp](../App/DomainModels/InkjetRecordsRepository.asp)
- [../App/Views/Kit/SwitchBoardPurpleEnvelopeEdit.asp](../App/Views/Kit/SwitchBoardPurpleEnvelopeEdit.asp)
- [../App/DomainModels/ColorsRepository.asp](../App/DomainModels/ColorsRepository.asp)

---

_Generated as a focused brownfield navigation guide._