Contractor Passport

Contractor Passport is a static Colorado contractor licensing and compliance reference site. It organizes fragmented city and county requirements for contractor licenses, renewals, insurance, workers' compensation, bonds, reciprocity, state-license dependencies, and official agency links.

This MVP is intentionally narrow: Colorado only, no database, no scraping, and no user accounts or paid services. Regulatory summaries must be verified against the linked official sources.

Data model

Jurisdiction records live in src/data/jurisdictions.json. Every record uses the following fields:

• id, name, type, and state
• requiresContractorLicense
• licenseClasses and tradesCovered
• renewalCycle and fees
• insuranceRequirements, workersCompRequirement, and bondRequirement
• reciprocity and stateLicenseDependency
• applicationUrl, renewalUrl, and lookupUrl
• sourceUrls
• lastVerified and confidence
• notes and gotchas

Use null, an empty array, or "Research required" for unknown values rather than guessing. Set confidence to high, medium, or low.

Commands

Requires Node.js 20 or newer.

npm run validate  # Validate required fields and data constraints
npm run generate  # Generate the static site in dist/
npm run build     # Validate, then generate
npm start         # Serve an existing dist/ directory on localhost:3000

Set BASE_URL when generating production pages so canonical URLs, the sitemap, and robots.txt use the deployed domain:

BASE_URL=https://contractorpassport.com npm run build

Without BASE_URL, generation uses https://contractorpassport.example as an obvious placeholder.

Deployment

The included netlify.toml tells Netlify to run npm run build and publish dist. In the Netlify site settings, add a BASE_URL environment variable containing the production origin with no trailing slash.

GitHub Actions validates and builds the project for pull requests and pushes to main.

Adding a jurisdiction

1. Add a complete record to src/data/jurisdictions.json.
2. Link only to official government or administering-agency sources.
3. Record the date the requirements were last checked in ISO format (YYYY-MM-DD).
4. Choose a confidence level based on the quality and completeness of the source research.
5. Run npm run build and review the generated page.

Next steps

• Research and replace placeholders for the five starter jurisdictions.
• Add the remaining Denver metro and Front Range MVP jurisdictions.
• Define a repeatable source-review checklist and confidence rubric.
• Add tests for representative generated HTML and malformed data.
• Configure the final domain and submit the sitemap after launch.