tracking_kits/docs/development-guide.md

tracking_kits - Development Guide

Date: 2026-03-13

Prerequisites

• Windows host with IIS
• Classic ASP enabled in IIS
• Access/Jet or ACE provider available
• COM dependencies installed if you need to exercise print/proof/export features
• Access to required local drives or network shares for non-dev environments

Local Setup

1. Configure an IIS site whose root points to the repository root.
2. Confirm index.asp is configured as the default document. The repo web.config already adds it.
3. Enable Classic ASP in IIS.
4. Review ../App/app.config.asp:
   • Routes.Initialize "/App/"
   • dev flag selection
   • ExportDirectory mapping
   • external CSS/JS URLs
5. If you need export/proof behavior, ensure the dependencies in ../Dependancies are present and registered appropriately on the machine.

Running the Application

• Browse the IIS site root.
• The browser is redirected from index.asp into the Home controller.
• Use the switchboard UI to access kit creation, tracking kits, purple envelope jobs, and custom office copy jobs.

Running Tests

• Open ../Tests/Test_All.asp through IIS.
• Expect coverage to focus on helper libraries and low-level utilities rather than full application workflows.

Working with the Database

• The app uses repositories and ADO, not an ORM.
• Sample MDB files exist in Data/.
• Schema evolution is implemented in ../Data/Migrations.
• Before changing a repository query, inspect the corresponding migration history and view usage.

Working with Reports and Exports

• Report definitions live in Data/*.rep.
• PDF/export code appears in KitController and import-service scripts.
• Many of these flows depend on file-system writes and COM objects, so static edits should be followed by manual Windows verification.

Common Brownfield Change Workflow

1. Identify the entry controller action and matching view.
2. Trace the repository calls and any related view-model class.
3. Check whether the same business rule also exists in ImportService/.
4. If persistence changes are needed, add a migration and update repository SQL.
5. Run helper tests if applicable.
6. Manually verify the affected page or export flow in IIS on Windows.

Code Conventions Observed

• Use Option Explicit at the top of ASP/VBScript files.
• Keep <!--#include file="..."--> directives near the top.
• Follow existing PascalCase naming for classes and descriptive file names.
• Match the surrounding indentation and spacing style.
• Avoid introducing new abstractions unless they reduce repeated controller/repository patterns.

Environment Caveats

• App/app.config.asp embeds environment switching and COM unlock behavior.
• ImportService/TrackingDataImport.vbs contains separate path/config handling from the web app.
• This workspace cannot validate IIS, COM registration, Jet/ACE, or network-share access.

Recommended Validation by Change Type

• View-only changes: Manual browser verification in IIS.
• Controller/repository changes: Browser verification plus targeted test runner pass if helper code changes.
• Schema changes: Migration review, repository validation, and manual smoke test.
• Proof/export changes: Windows-only manual verification of generated files and downstream handoff behavior.

---

Generated for brownfield analysis.