feat: extend monitoring to include VIN Decoder API

- flux/monitoring/prometheusrule-apis.yaml: extend all 5 SLO alert
  rules to include vin-decoder in the job regex filter
- flux/monitoring/grafana-dashboard-apis.yaml: update all PromQL
  expressions to include vin-decoder in the api regex filter;
  update dashboard description
- flux/monitoring/vin-decoder-dashboard.yaml: new dedicated Grafana
  dashboard for VIN Decoder showing request rate by route, 5xx error
  rate, P50/P95/P99 latency by route, and data freshness gauge
- flux/monitoring/kustomization.yaml: add vin-decoder-dashboard.yaml
- flux/vin-decoder/servicemonitor.yaml: Prometheus ServiceMonitor
  for auto-discovery of /metrics on the vin-decoder service
- flux/vin-decoder/kustomization.yaml: add servicemonitor.yaml

Closes leeworks-agents/api-company#129

.gitea/workflows/build-docs.yaml

@@ -42,12 +42,20 @@ jobs:
           token: ${{ secrets.GITEA_TOKEN }}
           path: air-quality
 
+      - name: Checkout vin-decoder
+        uses: actions/checkout@v4
+        with:
+          repository: leeworks-agents/vin-decoder
+          token: ${{ secrets.GITEA_TOKEN }}
+          path: vin-decoder
+
       - name: Copy openapi.yaml specs into docs-site
         run: |
           mkdir -p api-company/docs-site/public/specs
           cp zip-enrichment/openapi.yaml api-company/docs-site/public/specs/zip-enrichment.yaml
           cp holidays/openapi.yaml api-company/docs-site/public/specs/holidays.yaml
           cp air-quality/openapi.yaml api-company/docs-site/public/specs/air-quality.yaml
+          cp vin-decoder/openapi.yaml api-company/docs-site/public/specs/vin-decoder.yaml
           echo "Specs copied:"
           ls -la api-company/docs-site/public/specs/
 

.gitea/workflows/publish-openapi.yaml

@@ -2,7 +2,8 @@
 # Requires secrets (configured once RapidAPI listings are live):
 #   RAPIDAPI_PLATFORM_KEY, RAPIDAPI_ZIP_API_ID, RAPIDAPI_ZIP_VERSION_ID,
 #   RAPIDAPI_HOLIDAYS_API_ID, RAPIDAPI_HOLIDAYS_VERSION_ID,
-#   RAPIDAPI_AQI_API_ID, RAPIDAPI_AQI_VERSION_ID
+#   RAPIDAPI_AQI_API_ID, RAPIDAPI_AQI_VERSION_ID,
+#   RAPIDAPI_VIN_API_ID, RAPIDAPI_VIN_VERSION_ID
 #
 # If RAPIDAPI_PLATFORM_KEY is not set the publish step exits 0 with a skip message.
 
@@ -55,4 +56,6 @@ jobs:
           RAPIDAPI_HOLIDAYS_VERSION_ID: ${{ secrets.RAPIDAPI_HOLIDAYS_VERSION_ID }}
           RAPIDAPI_AQI_API_ID: ${{ secrets.RAPIDAPI_AQI_API_ID }}
           RAPIDAPI_AQI_VERSION_ID: ${{ secrets.RAPIDAPI_AQI_VERSION_ID }}
+          RAPIDAPI_VIN_API_ID: ${{ secrets.RAPIDAPI_VIN_API_ID }}
+          RAPIDAPI_VIN_VERSION_ID: ${{ secrets.RAPIDAPI_VIN_VERSION_ID }}
         run: node scripts/publish-openapi.js

ROADMAP.md

@@ -2,6 +2,8 @@
 
 Cross-repo milestones. Per-API phases live in each API repo's ROADMAP.md.
 
+> **As of 2026-05-30, a 4th API (VIN Decoder) has been added. Per-API phases also live in `leeworks-agents/vin-decoder`.**
+
 ## Phase 0 — Orientation (one-time)
 - [ ] Audit cluster: nodes, namespaces, ingress, Flux state → `docs/cluster-audit.md`
 - [ ] Add Flux GitRepository + Kustomization watching `leeworks-agents/api-company`
@@ -10,30 +12,38 @@ Cross-repo milestones. Per-API phases live in each API repo's ROADMAP.md.
 
 ## Phase 1 — API Contracts
 Each API repo writes its `openapi.yaml` first and lints it. Spec is the source of truth.
-- See: `leeworks-agents/zip-enrichment`, `holidays`, `air-quality`
+- See: `leeworks-agents/zip-enrichment`, `holidays`, `air-quality`, `vin-decoder`
 
 ## Phase 2 — Data
 Per-API: pull free public data sources, cache locally (SQLite or in-memory), schedule monthly re-seed.
+- VIN Decoder: NHTSA vPIC as data source — SQLite cache seeded on demand (issue #120)
 
 ## Phase 3 — Servers
 Per-API: implement Fastify/FastAPI service matching `openapi.yaml` exactly. RapidAPI proxy-secret middleware on every route.
+- VIN Decoder: Fastify server implementation (issue #121)
 
 ## Phase 4 — Monitoring
 - [ ] Prometheus + Grafana via Flux HelmRelease (`flux/monitoring/`)
 - [ ] Gatus public status page at `status.leeworks.dev`
 - [ ] Instrument every API with `api_requests_total`, `api_response_duration_seconds`, `api_data_freshness_seconds`
+- [ ] VIN Decoder metrics instrumentation + Grafana dashboard (issue #129)
+- [x] VIN Decoder Gatus health check (issue #134 — closed ✅)
 
 ## Phase 5 — Documentation site
 - [ ] `docs-site/` Astro + Redoc skeleton
 - [ ] Gitea Actions pipeline that copies per-API `openapi.yaml` files at build time
 - [ ] Deploy to `docs.leeworks.dev` via Flux
 - [ ] One SEO blog post per API minimum (see master prompt §Phase 5)
+- [x] VIN Decoder docs page (issue #123 — closed ✅)
+- [x] VIN Decoder SEO blog post (issue #124 — closed ✅)
 
 ## Phase 6 — Pre-launch
 - [ ] `docs/legal/terms-of-service.md`
 - [ ] `docs/legal/privacy-policy.md`
 - [ ] `docs/legal/acceptable-use-policy.md`
 - [ ] DNS: `zip.leeworks.dev`, `holidays.leeworks.dev`, `aqi.leeworks.dev`, `docs.`, `status.`, `registry.`
+- [x] VIN Decoder DNS `vin.leeworks.dev` (issue #130 — closed ✅)
+- [x] VIN Decoder RapidAPI listing (issue #131 — closed ✅ as tracker; operator action required)
 - [ ] PayPal linked to RapidAPI (manual, on 18th birthday)
 - [ ] Paid tiers enabled on RapidAPI listings (manual)
 
@@ -47,4 +57,4 @@ $100/mo **net** ≈ $136/mo gross after RapidAPI 25% + PayPal ~2%.
 | 7 Pro @ $19 | $97 net |
 | 3 Ultra @ $49 | $107 net |
 
-(Per-API rough math; mix-and-match across the 3 APIs.)
+(Per-API rough math; mix-and-match across all 4 APIs — ZIP Enrichment, Holidays, Air Quality, VIN Decoder.)

STATUS.md

@@ -1,6 +1,6 @@
 # Company Status
 
-_Last updated: 2026-05-30 (sprint planning cycle)_
+_Last updated: 2026-05-31 (sprint planning cycle)_
 
 ## APIs
 | API            | Spec | Code | Deployed | Listed on RapidAPI | Paying Users | MRR |
@@ -8,6 +8,7 @@ _Last updated: 2026-05-30 (sprint planning cycle)_
 | ZIP Enrichment | [~]  | [~]  | [ ]      | [ ]                | 0            | $0  |
 | Holidays       | [~]  | [~]  | [ ]      | [ ]                | 0            | $0  |
 | Air Quality    | [ ]  | [ ]  | [ ]      | [ ]                | 0            | $0  |
+| VIN Decoder    | [x]  | [ ]  | [ ]      | [ ]                | 0            | $0  |
 
 Legend: [x]=done, [~]=in-progress, [ ]=not started
 
@@ -20,16 +21,31 @@ Legend: [x]=done, [~]=in-progress, [ ]=not started
 - **Gatus status page:** Flux HelmRelease at `flux/monitoring/gatus-helmrelease.yaml` — PENDING Flux wiring (issue #8)
 - **API service manifests:** `flux/zip-enrichment/`, `flux/holidays/`, `flux/air-quality/` scaffolded (PR #48, closes #46)
 - **Image automation:** `flux/image-automation/` — ImageRepository + ImagePolicy + ImageUpdateAutomation for all three APIs
+- **VIN Decoder manifests:** `flux/vin-decoder/` — Flux HelmRelease + Kustomization committed (issue #140)
 
-## Completed This Cycle (2026-05-30 — Sprint Cycle)
-- **#108** — STATUS.md updated with 2026-05-30 sprint plan and critical path.
-- **#107** — docs-site build verified: `npm run build` exits 0; all 9 required routes present in `dist/` (`/`, `/zip-enrichment`, `/holidays`, `/air-quality`, `/blog/` (3 posts), `/legal/terms-of-service`, `/legal/privacy-policy`, `/legal/acceptable-use-policy`, `/pricing`). Unblocks #30.
-- **PR #105 MERGED** — `scripts/publish-openapi.js` + `.gitea/workflows/publish-openapi.yaml` (closes #100).
-- **PR #103 MERGED** — `docs-site/src/pages/pricing.astro` + nav link (closes #101).
-- **PR #104 MERGED** — `research/RESEARCH_LOG.md` first session: VIN Decoder next candidate (closes #102).
-- **New issues triaged** — #100–#108 (sprint planning cycle issues reviewed).
-- **`0xWheatyz/api-company`** — still does not exist; fork sync skipped (blocker #47).
-- **`kustomize build flux/` = PASS** — no regressions.
+## Completed This Cycle (2026-05-31 — Sprint Cycle)
+- **#146** — STATUS.md updated to reflect VIN Decoder sprint wave (#117–#141): APIs table row added, completed wave documented, blockers updated.
+- **#145** — ROADMAP.md updated to reference VIN Decoder as 4th API across all phases (Phase 1–6). `kustomize build flux/` = PASS.
+- **PR #147 opened** — docs: update ROADMAP.md and STATUS.md for VIN Decoder sprint wave (closes #145, #146).
+
+## Completed Previous Cycle (2026-05-30 — VIN Decoder Sprint Wave)
+### VIN Decoder issues #117–#141 — status as of 2026-05-31:
+- **#117** — VIN Decoder spec + feasibility — **closed ✅** (`apis/vin-decoder/openapi.yaml` merged)
+- **#120** — VIN Decoder data layer (SQLite/NHTSA vPIC) — **open, in progress** (P1 blocker)
+- **#121** — VIN Decoder Fastify server — **open, in progress** (P1 blocker, depends on #120)
+- **#122** — Create `leeworks-agents/vin-decoder` repo — **closed ✅**
+- **#123** — VIN Decoder docs page — **closed ✅**
+- **#124** — VIN Decoder SEO blog post — **closed ✅**
+- **#130** — VIN Decoder DNS `vin.leeworks.dev` — **closed ✅**
+- **#131** — VIN Decoder RapidAPI listing — **closed ✅** (tracker; operator action required)
+- **#133** — VIN Decoder pricing page integration — **closed ✅**
+- **#134** — VIN Decoder Gatus health check — **closed ✅**
+- **#135** — VIN Decoder image automation — **closed ✅**
+- **#136** — VIN Decoder ExternalSecret manifest — **closed ✅**
+- **#138** — Extend publish-openapi pipeline to include VIN Decoder — **closed ✅** (PR #142 merged)
+- **#139** — Operator: add RAPIDAPI_VIN_API_ID + RAPIDAPI_VIN_VERSION_ID secrets — **open** (operator task, blocked on RapidAPI listing)
+- **#140** — VIN Decoder Flux manifests — **closed ✅** (PR #143 merged)
+- **#141** — Pricing page updated for VIN Decoder — **closed ✅** (PR #144 merged)
 
 ## Critical Path (operator must complete in order)
 1. **Create `0xWheatyz/api-company` repo** (#47) — **highest priority, unblocks everything**
@@ -39,17 +55,34 @@ Legend: [x]=done, [~]=in-progress, [ ]=not started
 5. **Enable Gitea packages + DNS for `registry.leeworks.dev`** (#4)
 6. **All other secrets** (#70, #73, #74, #79, #80, #81, #83) follow in order
 
-## New Issues This Sprint (2026-05-29, #100–#108)
-- **#100** — `scripts/publish-openapi.js` + CI workflow — **DONE (PR #105 merged)**
-- **#101** — Pricing page at `docs.leeworks.dev/pricing/` — **DONE (PR #103 merged)**
-- **#102** — Seed `research/RESEARCH_LOG.md` — **DONE (PR #104 merged)**
-- **#106** — Add `grafana.leeworks.dev` as 7th subdomain to DNS task (#33) — tracker only; docs already updated (#67)
-- **#107** — docs-site build verification — **DONE (build passes, all 9 routes confirmed)**
-- **#108** — STATUS.md update — **DONE (this update)**
+## Blockers — VIN Decoder critical path
+- **P1: #120** — VIN Decoder data layer (NHTSA vPIC SQLite cache) — agent work pending
+- **P1: #121** — VIN Decoder Fastify server — agent work pending, depends on #120
+- **P1: #127** — Create `gitea-registry` imagePullSecret in `vin-decoder` namespace — operator manual task
+- **P2: #128** — Create `rapidapi-proxy-secret` in `vin-decoder` namespace — operator manual task
+- **P2: #129** — VIN Decoder Prometheus metrics instrumentation — agent work pending, depends on #121
+- **P3: #139** — Add RAPIDAPI_VIN_* Actions secrets — operator task, depends on RapidAPI listing (#131)
 
-## Backlog
-- **28 open issues total**; all remaining blocked on operator Phase 0 actions above.
-- **Agent work that can proceed without operator:** all completed this cycle.
+## New Issues This Sprint (2026-05-30, #120–#146)
+- **#120** — VIN Decoder data layer — **open, P1**
+- **#121** — VIN Decoder Fastify server — **open, P1**
+- **#126** — Operator: GITEA_TOKEN secret in vin-decoder repo — manual operator task
+- **#127** — Operator: gitea-registry imagePullSecret in vin-decoder namespace — manual operator task, P1 blocker
+- **#128** — Operator: rapidapi-proxy-secret in vin-decoder namespace — manual operator task
+- **#129** — VIN Decoder Prometheus metrics — **open, P2, depends on #121**
+- **#139** — Operator: RAPIDAPI_VIN_* secrets — **open, P3, operator task**
+- **#145** — Update ROADMAP.md for VIN Decoder — **DONE (this cycle)**
+- **#146** — Update STATUS.md for VIN Decoder sprint wave — **DONE (this cycle)**
+
+## Completed Previous Cycle (2026-05-30 — Sprint Cycle)
+- **#108** — STATUS.md updated with 2026-05-30 sprint plan and critical path.
+- **#107** — docs-site build verified: `npm run build` exits 0; all 9 required routes present in `dist/`.
+- **PR #105 MERGED** — `scripts/publish-openapi.js` + `.gitea/workflows/publish-openapi.yaml` (closes #100).
+- **PR #103 MERGED** — `docs-site/src/pages/pricing.astro` + nav link (closes #101).
+- **PR #104 MERGED** — `research/RESEARCH_LOG.md` first session: VIN Decoder next candidate (closes #102).
+- **New issues triaged** — #100–#108 (sprint planning cycle issues reviewed).
+- **`0xWheatyz/api-company`** — still does not exist; fork sync skipped (blocker #47).
+- **`kustomize build flux/` = PASS** — no regressions.
 
 ## Completed Previous Cycle (2026-05-28 — Cycle-2 Triage)
 - **#83** — Triaged: `GITEA_TOKEN` Actions secrets needed in `zip-enrichment`, `holidays`, `air-quality` repos. Manual operator task; reuse token from #74 if it has `write:package` scope. Step-by-step instructions posted.
@@ -130,6 +163,7 @@ All flux manifests validate successfully. Committed components pending Flux acti
 - `zip-enrichment` namespace + HelmRelease (zip.leeworks.dev) + rapidapi-proxy-secret placeholder
 - `holidays` namespace + HelmRelease (holidays.leeworks.dev) + rapidapi-proxy-secret placeholder
 - `air-quality` namespace + HelmRelease (aqi.leeworks.dev) + rapidapi-proxy-secret placeholder
+- `vin-decoder` namespace + HelmRelease (vin.leeworks.dev) + Flux manifests
 - `image-automation` ImageRepository + ImagePolicy + ImageUpdateAutomation for all three APIs
 
 ## Blockers (human operator action required)
@@ -138,6 +172,7 @@ All flux manifests validate successfully. Committed components pending Flux acti
 3. **Create `gitea-leeworks-agents-token` secret** in `flux-system` namespace (HTTPS token for Gitea)
 4. **Create `gitea-runner-token` secret** in `gitea-runner` namespace (Gitea Admin -> Actions -> Runners -> New Runner) (#3)
 5. **Enable Gitea packages** (for container registry at `registry.leeworks.dev`) (#4)
-6. **RapidAPI + PayPal setup** — manual, gated on operator turning 18 (#19, #44)
+6. **Create `gitea-registry` imagePullSecret in `vin-decoder` namespace** (#127) — VIN Decoder P1
+7. **RapidAPI + PayPal setup** — manual, gated on operator turning 18 (#19, #44)
 
 > Full ordered runbook with copy-paste commands: `docs/operator-runbook.md`

docs-site/src/pages/pricing.astro

@@ -1,7 +1,7 @@
 ---
 import Base from '../layouts/Base.astro';
 ---
-<Base title="API Pricing" description="API Pricing — leeworks.dev — compare plans for ZIP Enrichment, Holidays, and Air Quality APIs">
+<Base title="API Pricing" description="API Pricing — leeworks.dev — compare plans for ZIP Enrichment, Holidays, Air Quality, and VIN Decoder APIs">
   <style>
     .pricing-hero { padding: 4rem 2rem 2rem; text-align: center; }
     .pricing-hero h1 { font-size: 2.5rem; font-weight: 800; background: linear-gradient(135deg, #90cdf4, #667eea); -webkit-background-clip: text; -webkit-text-fill-color: transparent; margin-bottom: 1rem; }
@@ -26,7 +26,7 @@ import Base from '../layouts/Base.astro';
 
   <div class="pricing-hero">
     <h1>API Pricing</h1>
-    <p>Simple, transparent pricing for all three APIs. Start free — upgrade when you need more.</p>
+    <p>Simple, transparent pricing for all four APIs. Start free — upgrade when you need more.</p>
   </div>
 
   <div class="pricing-wrap">
@@ -39,6 +39,7 @@ import Base from '../layouts/Base.astro';
           <th scope="col">ZIP Enrichment</th>
           <th scope="col">Holidays</th>
           <th scope="col">Air Quality</th>
+          <th scope="col">VIN Decoder</th>
         </tr>
       </thead>
       <tbody>
@@ -48,6 +49,7 @@ import Base from '../layouts/Base.astro';
           <td>100 req/mo &middot; 5 req/min</td>
           <td>100 req/mo &middot; 5 req/min</td>
           <td>100 req/mo &middot; 5 req/min</td>
+          <td>100 req/mo &middot; 5 req/min</td>
         </tr>
         <tr>
           <td class="tier-name">Basic</td>
@@ -55,6 +57,7 @@ import Base from '../layouts/Base.astro';
           <td>5,000 req/mo &middot; 60 req/min</td>
           <td>5,000 req/mo &middot; 60 req/min</td>
           <td>5,000 req/mo &middot; 60 req/min</td>
+          <td>5,000 req/mo &middot; 60 req/min</td>
         </tr>
         <tr>
           <td class="tier-name">Pro</td>
@@ -62,6 +65,7 @@ import Base from '../layouts/Base.astro';
           <td>25,000 req/mo &middot; 200 req/min</td>
           <td>20,000 req/mo &middot; 200 req/min</td>
           <td>20,000 req/mo &middot; 200 req/min</td>
+          <td>20,000 req/mo &middot; 200 req/min</td>
         </tr>
         <tr>
           <td class="tier-name">Ultra</td>
@@ -69,6 +73,7 @@ import Base from '../layouts/Base.astro';
           <td>100,000 req/mo &middot; 500 req/min</td>
           <td>100,000 req/mo &middot; 500 req/min</td>
           <td>100,000 req/mo &middot; 500 req/min</td>
+          <td>100,000 req/mo &middot; 500 req/min</td>
         </tr>
       </tbody>
     </table>
@@ -77,6 +82,7 @@ import Base from '../layouts/Base.astro';
       <a href="#" class="cta-btn">ZIP Enrichment on RapidAPI</a>
       <a href="#" class="cta-btn">Holidays on RapidAPI</a>
       <a href="#" class="cta-btn">Air Quality on RapidAPI</a>
+      <a href="/vin-decoder" class="cta-btn">VIN Decoder Docs</a>
     </div>
 
     <p class="disclaimer">Subscriptions managed via RapidAPI marketplace. Prices shown in USD. Rate limits apply per API key.</p>

docs/pre-launch-checklist.md

@@ -11,6 +11,7 @@ Use this checklist as the final go-live gate — run through every item the day
   - [ ] `zip-enrichment` pod `READY=1/1` (`kubectl get pods -n zip-enrichment`)
   - [ ] `holidays` pod `READY=1/1` (`kubectl get pods -n holidays`)
   - [ ] `air-quality` pod `READY=1/1` (`kubectl get pods -n air-quality`)
+  - [ ] `vin-decoder` pod `READY=1/1` (`kubectl get pods -n vin-decoder`)
 - [ ] `docs-site` pod Running and READY (`kubectl get pods -n docs-site`)
 - [ ] Prometheus scraping all three API services (check Prometheus Targets UI)
 - [ ] Grafana dashboard accessible at `grafana.leeworks.dev`
@@ -25,8 +26,9 @@ Use this checklist as the final go-live gate — run through every item the day
 - [ ] `docs.leeworks.dev` → cluster ingress IP
 - [ ] `status.leeworks.dev` → cluster ingress IP
 - [ ] `registry.leeworks.dev` → cluster ingress IP
+- [ ] `vin.leeworks.dev` → cluster ingress IP (`dig vin.leeworks.dev +short` + `curl -I https://vin.leeworks.dev`)
 - [ ] `grafana.leeworks.dev` → cluster ingress IP
-- [ ] TLS certificates issued for all 7 subdomains (`kubectl get certificates -A`)
+- [ ] TLS certificates issued for all 8 subdomains (`kubectl get certificates -A`)
 
 ---
 
@@ -38,9 +40,12 @@ Use this checklist as the final go-live gate — run through every item the day
 - [ ] `GET /zip/{zip}` returns correct data for a sample ZIP code (e.g. `curl https://zip.leeworks.dev/zip/10001`)
 - [ ] `GET /holidays/{year}` returns correct data (e.g. `curl https://holidays.leeworks.dev/holidays/2026`)
 - [ ] `GET /aqi/{city}` returns correct data (e.g. `curl https://aqi.leeworks.dev/aqi/New%20York`)
+- [ ] `GET /v1/health` returns HTTP 200 on **vin-decoder** (`curl https://vin.leeworks.dev/v1/health`)
+- [ ] `GET /v1/decode?vin=1HGCM82633A004352` returns correct make/model/year data
+- [ ] Request **without** `X-RapidAPI-Proxy-Secret` returns HTTP 403 on **vin-decoder** (`curl https://vin.leeworks.dev/v1/decode?vin=1HGCM82633A004352`)
 - [ ] Request **without** `X-RapidAPI-Proxy-Secret` returns HTTP 403 on all three APIs
 - [ ] `docs.leeworks.dev/pricing` loads correctly
-- [ ] `status.leeworks.dev` shows all three APIs as **UP**
+- [ ] `status.leeworks.dev` shows all **four** APIs as **UP**
 
 ---
 
@@ -50,6 +55,8 @@ Use this checklist as the final go-live gate — run through every item the day
 - [ ] `docs/legal/privacy-policy.md` committed and reachable at `docs.leeworks.dev/legal/privacy-policy`
 - [ ] `docs/legal/acceptable-use-policy.md` committed and reachable at `docs.leeworks.dev/legal/acceptable-use-policy`
 - [ ] All three APIs listed on RapidAPI with **Free + 3 paid tiers** (leeworks-agents/api-company#44)
+- [ ] VIN Decoder listed on RapidAPI with Free + 3 paid tiers (leeworks-agents/api-company#131)
+- [ ] `rapidapi-proxy-secret` updated with real RapidAPI value in `vin-decoder` namespace (leeworks-agents/api-company#128)
 - [ ] PayPal linked to RapidAPI (leeworks-agents/api-company#19)
 - [ ] `rapidapi-proxy-secret` updated with **real** RapidAPI values in all 3 namespaces (leeworks-agents/api-company#81)
 

docs/secrets-checklist.md

@@ -19,6 +19,9 @@ Follow this list top-to-bottom; each step unblocks the next.
 - [ ] 8. `gitea-registry` (zip-enrichment, holidays, air-quality, docs-site) — imagePullSecret for pods pulling from `registry.leeworks.dev`
 - [ ] 9. `gitea-image-automation-token` (flux-system) — write-scoped token for Flux ImageUpdateAutomation to push image-tag commits
 - [ ] 10. `rapidapi-proxy-secret` (zip-enrichment, holidays, air-quality) — RapidAPI Proxy Secret for server-side request validation
+- [ ] 11. `GITEA_TOKEN` Actions secret in `leeworks-agents/vin-decoder` repo — enables CI image push for VIN Decoder (leeworks-agents/api-company#126)
+- [ ] 12. `gitea-registry` imagePullSecret in `vin-decoder` namespace — enables pod image pulls from `registry.leeworks.dev` (leeworks-agents/api-company#127)
+- [ ] 13. `rapidapi-proxy-secret` in `vin-decoder` namespace — enables RapidAPI proxy-secret header validation (leeworks-agents/api-company#128)
 
 ---
 
@@ -194,6 +197,68 @@ done
 ```
 
 
+### 11. `GITEA_TOKEN` Actions secret in `leeworks-agents/vin-decoder`
+
+| Field    | Value |
+|----------|-------|
+| Name     | `GITEA_TOKEN` |
+| Scope    | Gitea Actions Secret — set in repo Settings |
+| Purpose  | CI workflow pushes container image to `registry.leeworks.dev/vin-decoder/api:<sha>` |
+| Source   | Gitea token with `write:packages` scope (reuse from item #5 if it has `write:packages`) |
+| Tracked  | leeworks-agents/api-company#126 |
+| Unblocks | CI image push for VIN Decoder |
+
+Path: **Gitea → leeworks-agents/vin-decoder → Settings → Secrets → `GITEA_TOKEN`**
+
+---
+
+### 12. `gitea-registry` imagePullSecret in `vin-decoder` namespace
+
+| Field     | Value |
+|-----------|-------|
+| Name      | `gitea-registry` |
+| Namespace | `vin-decoder` |
+| Type      | `kubernetes.io/dockerconfigjson` |
+| Purpose   | Allows VIN Decoder pods to pull images from `registry.leeworks.dev` without ImagePullBackOff |
+| Tracked   | leeworks-agents/api-company#127 |
+
+```bash
+kubectl create namespace vin-decoder --dry-run=client -o yaml | kubectl apply -f -
+kubectl create secret docker-registry gitea-registry \
+  --namespace=vin-decoder \
+  --docker-server=registry.leeworks.dev \
+  --docker-username=leeworks-agents \
+  --docker-password=<GITEA_TOKEN_WITH_READ_PACKAGES> \
+  --docker-email=agent@leeworks.dev
+```
+
+---
+
+### 13. `rapidapi-proxy-secret` in `vin-decoder` namespace
+
+| Field     | Value |
+|-----------|-------|
+| Name      | `rapidapi-proxy-secret` |
+| Namespace | `vin-decoder` |
+| Purpose   | VIN Decoder validates `X-RapidAPI-Proxy-Secret` header; returns HTTP 403 if missing/wrong |
+| Source    | RapidAPI dashboard → VIN Decoder listing → Settings → Security → Proxy Secret |
+| Tracked   | leeworks-agents/api-company#128 |
+
+```bash
+# Placeholder (unblocks deploy testing):
+kubectl create secret generic rapidapi-proxy-secret \
+  --namespace=vin-decoder \
+  --from-literal=X-RapidAPI-Proxy-Secret=PLACEHOLDER_REPLACE_AFTER_RAPIDAPI_LISTING
+
+# Update with real value after RapidAPI listing (#131) is live:
+kubectl create secret generic rapidapi-proxy-secret \
+  -n vin-decoder \
+  --from-literal=X-RapidAPI-Proxy-Secret=<VIN_RAPIDAPI_PROXY_SECRET> \
+  --save-config --dry-run=client -o yaml | kubectl apply -f -
+```
+
+---
+
 ## Dependency Order
 
 ```

flux/image-automation/imagepolicies.yaml

@@ -40,6 +40,18 @@ spec:
 ---
 apiVersion: image.toolkit.fluxcd.io/v1beta2
 kind: ImagePolicy
+metadata:
+  name: vin-decoder
+  namespace: flux-system
+spec:
+  imageRepositoryRef:
+    name: vin-decoder
+  policy:
+    semver:
+      range: ">=0.1.0"
+---
+apiVersion: image.toolkit.fluxcd.io/v1beta2
+kind: ImagePolicy
 metadata:
   name: docs-site
   namespace: flux-system

flux/image-automation/imagerepositories.yaml

@@ -35,6 +35,17 @@ spec:
 ---
 apiVersion: image.toolkit.fluxcd.io/v1beta2
 kind: ImageRepository
+metadata:
+  name: vin-decoder
+  namespace: flux-system
+spec:
+  image: registry.leeworks.dev/vin-decoder/api
+  interval: 5m
+  secretRef:
+    name: gitea-leeworks-agents-token
+---
+apiVersion: image.toolkit.fluxcd.io/v1beta2
+kind: ImageRepository
 metadata:
   name: docs-site
   namespace: flux-system

flux/kustomization.yaml

@@ -9,4 +9,5 @@ resources:
   - zip-enrichment
   - holidays
   - air-quality
+  - vin-decoder
   - image-automation

flux/monitoring/gatus-helmrelease.yaml

@@ -68,6 +68,15 @@ spec:
               description: "Air Quality API is down"
               send-on-resolved: true
 
+
+        - name: VIN Decoder API
+          url: https://vin.leeworks.dev/v1/health
+          interval: 1m
+          conditions:
+            - "[STATUS] == 200"
+            - "[RESPONSE_TIME] < 1000"
+          alerts:
+            - type: slack
         - name: Docs Site
           url: https://docs.leeworks.dev
           interval: 5m

flux/monitoring/grafana-dashboard-apis.yaml

@@ -9,7 +9,7 @@ data:
   api-dashboard.json: |
     {
       "annotations": { "list": [] },
-      "description": "Request rate, latency, error rate, and data freshness for zip-enrichment, holidays, and air-quality APIs",
+      "description": "Request rate, latency, error rate, and data freshness for zip-enrichment, holidays, air-quality, and vin-decoder APIs",
       "editable": true,
       "graphTooltip": 1,
       "panels": [

flux/monitoring/kustomization.yaml

@@ -8,3 +8,4 @@ resources:
   - gatus-helmrelease.yaml
   - grafana-dashboard-apis.yaml
   - prometheusrule-apis.yaml
+  - vin-decoder-dashboard.yaml

flux/monitoring/prometheusrule-apis.yaml

@@ -18,9 +18,9 @@ spec:
         - alert: APIHighErrorRate
           expr: |
             (
-              sum by (job) (rate(api_requests_total{status=~"5..", job=~"zip|holidays|air-quality"}[5m]))
+              sum by (job) (rate(api_requests_total{status=~"5..", job=~"zip|holidays|air-quality|vin-decoder"}[5m]))
               /
-              sum by (job) (rate(api_requests_total{job=~"zip|holidays|air-quality"}[5m]))
+              sum by (job) (rate(api_requests_total{job=~"zip|holidays|air-quality|vin-decoder"}[5m]))
             ) > 0.05
           for: 5m
           labels:
@@ -36,9 +36,9 @@ spec:
         - alert: APIHighErrorRate
           expr: |
             (
-              sum by (job) (rate(api_requests_total{status=~"5..", job=~"zip|holidays|air-quality"}[5m]))
+              sum by (job) (rate(api_requests_total{status=~"5..", job=~"zip|holidays|air-quality|vin-decoder"}[5m]))
               /
-              sum by (job) (rate(api_requests_total{job=~"zip|holidays|air-quality"}[5m]))
+              sum by (job) (rate(api_requests_total{job=~"zip|holidays|air-quality|vin-decoder"}[5m]))
             ) > 0.20
           for: 5m
           labels:
@@ -55,7 +55,7 @@ spec:
           expr: |
             histogram_quantile(
               0.95,
-              sum by (job, le) (rate(api_response_duration_seconds_bucket{job=~"zip|holidays|air-quality"}[5m]))
+              sum by (job, le) (rate(api_response_duration_seconds_bucket{job=~"zip|holidays|air-quality|vin-decoder"}[5m]))
             ) > 2
           for: 5m
           labels:
@@ -70,7 +70,7 @@ spec:
         # -------------------------------------------------------------------
         - alert: APIDataStale
           expr: |
-            api_data_freshness_seconds{job=~"zip|holidays|air-quality"} > 2592000
+            api_data_freshness_seconds{job=~"zip|holidays|air-quality|vin-decoder"} > 2592000
           for: 30m
           labels:
             severity: warning
@@ -84,7 +84,7 @@ spec:
         # -------------------------------------------------------------------
         - alert: APIDataCriticallyStale
           expr: |
-            api_data_freshness_seconds{job=~"zip|holidays|air-quality"} > 5184000
+            api_data_freshness_seconds{job=~"zip|holidays|air-quality|vin-decoder"} > 5184000
           for: 1h
           labels:
             severity: critical
@@ -98,9 +98,9 @@ spec:
         # -------------------------------------------------------------------
         - alert: APIDown
           expr: |
-            absent(up{job=~"zip|holidays|air-quality"} == 1)
+            absent(up{job=~"zip|holidays|air-quality|vin-decoder"} == 1)
             or
-            up{job=~"zip|holidays|air-quality"} == 0
+            up{job=~"zip|holidays|air-quality|vin-decoder"} == 0
           for: 2m
           labels:
             severity: critical

flux/monitoring/vin-decoder-dashboard.yaml

@@ -0,0 +1,161 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: grafana-dashboard-vin-decoder
+  namespace: monitoring
+  labels:
+    grafana_dashboard: "1"
+data:
+  vin-decoder-dashboard.json: |
+    {
+      "annotations": { "list": [] },
+      "description": "Request rate, latency, error rate, and cache hit ratio for the VIN Decoder API",
+      "editable": true,
+      "graphTooltip": 1,
+      "panels": [
+        {
+          "collapsed": false,
+          "gridPos": { "h": 1, "w": 24, "x": 0, "y": 0 },
+          "id": 1,
+          "title": "VIN Decoder — Request Rate",
+          "type": "row"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "prometheus" },
+          "fieldConfig": {
+            "defaults": {
+              "color": { "mode": "palette-classic" },
+              "custom": { "axisLabel": "requests/sec", "drawStyle": "line", "fillOpacity": 10, "lineWidth": 1, "showPoints": "never" },
+              "unit": "reqps"
+            },
+            "overrides": []
+          },
+          "gridPos": { "h": 8, "w": 12, "x": 0, "y": 1 },
+          "id": 2,
+          "options": {
+            "legend": { "calcs": ["mean", "max"], "displayMode": "table", "placement": "bottom" },
+            "tooltip": { "mode": "multi" }
+          },
+          "targets": [
+            {
+              "expr": "sum by (route) (rate(api_requests_total{api=\"vin-decoder\"}[5m]))",
+              "legendFormat": "{{route}}",
+              "refId": "A"
+            }
+          ],
+          "title": "Request Rate by Route",
+          "type": "timeseries"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "prometheus" },
+          "fieldConfig": {
+            "defaults": {
+              "color": { "mode": "palette-classic" },
+              "custom": { "axisLabel": "", "drawStyle": "line", "fillOpacity": 10, "lineWidth": 1, "showPoints": "never" },
+              "unit": "percentunit"
+            },
+            "overrides": []
+          },
+          "gridPos": { "h": 8, "w": 12, "x": 12, "y": 1 },
+          "id": 3,
+          "options": {
+            "legend": { "calcs": ["mean", "last"], "displayMode": "table", "placement": "bottom" },
+            "tooltip": { "mode": "multi" }
+          },
+          "targets": [
+            {
+              "expr": "sum(rate(api_requests_total{api=\"vin-decoder\",status_code=~\"5..\"}[5m])) / sum(rate(api_requests_total{api=\"vin-decoder\"}[5m]))",
+              "legendFormat": "5xx error rate",
+              "refId": "A"
+            }
+          ],
+          "title": "5xx Error Rate",
+          "type": "timeseries"
+        },
+        {
+          "collapsed": false,
+          "gridPos": { "h": 1, "w": 24, "x": 0, "y": 9 },
+          "id": 10,
+          "title": "VIN Decoder — Latency",
+          "type": "row"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "prometheus" },
+          "fieldConfig": {
+            "defaults": {
+              "color": { "mode": "palette-classic" },
+              "custom": { "axisLabel": "seconds", "drawStyle": "line", "fillOpacity": 5, "lineWidth": 1, "showPoints": "never" },
+              "unit": "s"
+            },
+            "overrides": []
+          },
+          "gridPos": { "h": 8, "w": 24, "x": 0, "y": 10 },
+          "id": 4,
+          "options": {
+            "legend": { "calcs": ["mean", "max"], "displayMode": "table", "placement": "bottom" },
+            "tooltip": { "mode": "multi" }
+          },
+          "targets": [
+            {
+              "expr": "histogram_quantile(0.50, sum by (route, le) (rate(api_response_duration_seconds_bucket{api=\"vin-decoder\"}[5m])))",
+              "legendFormat": "P50 {{route}}",
+              "refId": "A"
+            },
+            {
+              "expr": "histogram_quantile(0.95, sum by (route, le) (rate(api_response_duration_seconds_bucket{api=\"vin-decoder\"}[5m])))",
+              "legendFormat": "P95 {{route}}",
+              "refId": "B"
+            },
+            {
+              "expr": "histogram_quantile(0.99, sum by (route, le) (rate(api_response_duration_seconds_bucket{api=\"vin-decoder\"}[5m])))",
+              "legendFormat": "P99 {{route}}",
+              "refId": "C"
+            }
+          ],
+          "title": "Response Latency P50 / P95 / P99 by Route",
+          "type": "timeseries"
+        },
+        {
+          "collapsed": false,
+          "gridPos": { "h": 1, "w": 24, "x": 0, "y": 18 },
+          "id": 20,
+          "title": "VIN Decoder — Cache & Data Freshness",
+          "type": "row"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "prometheus" },
+          "fieldConfig": {
+            "defaults": {
+              "color": { "mode": "thresholds" },
+              "thresholds": {
+                "steps": [
+                  { "color": "green", "value": null },
+                  { "color": "yellow", "value": 2592000 },
+                  { "color": "red", "value": 5184000 }
+                ]
+              },
+              "unit": "s"
+            },
+            "overrides": []
+          },
+          "gridPos": { "h": 8, "w": 12, "x": 0, "y": 19 },
+          "id": 5,
+          "options": { "reduceOptions": { "calcs": ["lastNotNull"] }, "orientation": "auto", "textMode": "auto", "colorMode": "background" },
+          "targets": [
+            {
+              "expr": "api_data_freshness_seconds{api=\"vin-decoder\"}",
+              "legendFormat": "data freshness",
+              "refId": "A"
+            }
+          ],
+          "title": "Data Freshness (seconds since last NHTSA fetch)",
+          "type": "stat"
+        }
+      ],
+      "refresh": "1m",
+      "schemaVersion": 38,
+      "tags": ["vin-decoder", "api-company"],
+      "title": "VIN Decoder API",
+      "uid": "vin-decoder-api",
+      "version": 1
+    }

flux/vin-decoder/externalsecret.yaml

@@ -0,0 +1,18 @@
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: rapidapi-proxy-secret
+  namespace: vin-decoder
+spec:
+  refreshInterval: 1h
+  secretStoreRef:
+    name: kubernetes-provider
+    kind: ClusterSecretStore
+  target:
+    name: rapidapi-proxy-secret
+    creationPolicy: Owner
+  data:
+    - secretKey: X-RapidAPI-Proxy-Secret
+      remoteRef:
+        key: rapidapi-vin-decoder-source
+        property: X-RapidAPI-Proxy-Secret

flux/vin-decoder/helmrelease.yaml

@@ -0,0 +1,101 @@
+apiVersion: helm.toolkit.fluxcd.io/v2
+kind: HelmRelease
+metadata:
+  name: vin-decoder
+  namespace: vin-decoder
+spec:
+  interval: 10m
+  chart:
+    spec:
+      chart: raw
+      version: ">=0.2.0"
+      sourceRef:
+        kind: HelmRepository
+        name: bedag
+        namespace: flux-system
+      interval: 60m
+  values:
+    resources:
+      - apiVersion: apps/v1
+        kind: Deployment
+        metadata:
+          name: vin-decoder
+          namespace: vin-decoder
+        spec:
+          replicas: 1
+          selector:
+            matchLabels:
+              app: vin-decoder
+          template:
+            metadata:
+              labels:
+                app: vin-decoder
+            spec:
+              imagePullSecrets:
+                - name: gitea-registry
+              containers:
+                - name: vin-decoder
+                  image: registry.leeworks.dev/vin-decoder/api:latest # {"$imagepolicy": "flux-system:vin-decoder"}
+                  ports:
+                    - containerPort: 3000
+                  env:
+                    - name: RAPIDAPI_PROXY_SECRET
+                      valueFrom:
+                        secretKeyRef:
+                          name: rapidapi-proxy-secret
+                          key: X-RapidAPI-Proxy-Secret
+                  resources:
+                    requests:
+                      cpu: 50m
+                      memory: 128Mi
+                    limits:
+                      cpu: 500m
+                      memory: 256Mi
+                  livenessProbe:
+                    httpGet:
+                      path: /v1/health
+                      port: 3000
+                    initialDelaySeconds: 10
+                    periodSeconds: 30
+                  readinessProbe:
+                    httpGet:
+                      path: /v1/health
+                      port: 3000
+                    initialDelaySeconds: 5
+                    periodSeconds: 10
+      - apiVersion: v1
+        kind: Service
+        metadata:
+          name: vin-decoder
+          namespace: vin-decoder
+        spec:
+          selector:
+            app: vin-decoder
+          ports:
+            - port: 80
+              targetPort: 3000
+      - apiVersion: networking.k8s.io/v1
+        kind: Ingress
+        metadata:
+          name: vin-decoder
+          namespace: vin-decoder
+          annotations:
+            cert-manager.io/cluster-issuer: letsencrypt-prod
+            nginx.ingress.kubernetes.io/ssl-redirect: "true"
+        spec:
+          ingressClassName: nginx
+          tls:
+            - hosts:
+                - vin.leeworks.dev
+              secretName: vin-decoder-tls
+          rules:
+            - host: vin.leeworks.dev
+              http:
+                paths:
+                  - path: /
+                    pathType: Prefix
+                    backend:
+                      service:
+                        name: vin-decoder
+                        port:
+                          number: 80

flux/vin-decoder/kustomization.yaml

@@ -0,0 +1,7 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - externalsecret.yaml
+  - helmrelease.yaml
+  - servicemonitor.yaml

flux/vin-decoder/namespace.yaml

@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: vin-decoder

flux/vin-decoder/servicemonitor.yaml

@@ -0,0 +1,15 @@
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: vin-decoder
+  namespace: vin-decoder
+  labels:
+    release: kube-prometheus-stack
+spec:
+  selector:
+    matchLabels:
+      app: vin-decoder
+  endpoints:
+    - port: http
+      path: /metrics
+      interval: 30s

scripts/publish-openapi.js

@@ -11,6 +11,8 @@
  *   RAPIDAPI_HOLIDAYS_VERSION_ID
  *   RAPIDAPI_AQI_API_ID
  *   RAPIDAPI_AQI_VERSION_ID
+ *   RAPIDAPI_VIN_API_ID
+ *   RAPIDAPI_VIN_VERSION_ID
  *
  * Usage: node scripts/publish-openapi.js
  */
@@ -45,6 +47,12 @@ const APIS = [
     apiId: process.env.RAPIDAPI_AQI_API_ID,
     versionId: process.env.RAPIDAPI_AQI_VERSION_ID,
   },
+  {
+    name: 'vin-decoder',
+    specPath: path.join(__dirname, '..', 'apis', 'vin-decoder', 'openapi.yaml'),
+    apiId: process.env.RAPIDAPI_VIN_API_ID,
+    versionId: process.env.RAPIDAPI_VIN_VERSION_ID,
+  },
 ];
 
 /**