dcovington
/
tracking_kits
1
0
Fork 0
Code Issues 0 Pull Requests 0 Releases 0 Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
117 Commits
1 Branch
791MB
Tree: 201f1419e2
Branches Tags
${ item.name }
Create branch ${ searchTerm }
from '201f1419e2'
${ noResults }
tracking_kits/docs/module-map.md

11KB
Raw Blame History

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:

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

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

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

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

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
  • 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

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

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

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:

“Change jurisdiction import behavior”

Open:

“Change export file format or proof output”

Open:

“Change purple-envelope or inkjet assignment logic”

Open:

Generated as a focused brownfield navigation guide.

Powered by TurnKey Linux.