Codebase Audit Report

Executive Summary

The codebase implements a Cloudflare Workers API with Neon PostgreSQL. Authentication (Google OAuth + Turnstile) is designed but not yet implemented. Core infrastructure is operational.

Component	Status
Worker Entry Point	OK
DB Abstraction (pg/Neon)	OK
Dev Environment Protection	OK
Webhook Deploy Pipeline	OK
Google OAuth	Missing
Turnstile Bot Protection	Missing
Session Management	Missing
Database Schema	Missing
Metering System	Missing

Key Questions Answered

Q1: Which user actions trigger a database request?

Current state: Only GET /health triggers a DB query.

Route	DB Query	File:Line
`GET /health`	`SELECT NOW()`	src/index.js:40
`GET /`	None	src/index.js:48

Grep pattern: rg "query\(env," src/

Q2: Which user actions should be metered?

Current state: No metering annotations exist. Recommended metered actions:

@metered - Any route hitting Neon (compute cost)
@metered - OAuth token exchanges (rate limit sensitive)
@metered - File uploads (future)

Implementation needed: Add @metered JSDoc tags to controllers.

Grep pattern: rg "@metered" src/

Q3: How do we track metered usage in serverless?

Recommended pattern:

Each @metered endpoint emits UsageEvent to Cloudflare Queue
Queue consumer aggregates by user_id + action
Store aggregates in Neon with batch writes (reduce compute)
Query aggregates for billing/limits

Not blocking request path - fire-and-forget to queue.

Architecture Compliance

SOLID Principles

Principle	Status	Notes
Single Responsibility	OK	`src/index.js` = routing only, `src/db/` = data access
Open/Closed	Warn	Need controller pattern - currently inline handlers
Liskov Substitution	N/A	No inheritance hierarchy yet
Interface Segregation	OK	Minimal `query()` interface
Dependency Inversion	OK	DB driver abstraction hides pg vs Neon

Rule Compliance

Rule	Status	Evidence
No fallback env vars	Warn	`src/db/index.js:27-31` uses fallbacks for local dev
No speculative code	Warn	`items` table in `init.sql` is placeholder
File naming convention	Missing	No controllers yet - will need `get-*.controller.js`
Git worktrees	OK	Rule documented, agents can follow
Never commit to main	OK	Webhook enforces PR workflow

Security Review

Check	Status	Details
SQL Injection	OK	Parameterized queries via `query(env, sql, params)`
Env Protection (Non-Prod)	OK	`X-Dev-Token` required before any DB call
Secrets in Code	OK	All secrets via `wrangler secret put`
Auth on Protected Routes	Missing	No auth middleware implemented yet
HTTPS	OK	Enforced by Cloudflare edge

Critical: Local DB Fallbacks

src/db/index.js:27-31 uses hardcoded fallbacks for local testing. These violate the strict-env-config rule. Recommend: separate test config file or explicit test environment detection.

File Inventory

Source Files

File	Purpose	DB Access
src/index.js	Worker entry, routing	Yes (health)
src/db/index.js	DB abstraction layer	Core
webhook/server.js	GitHub webhook handler	No

Configuration

File	Purpose
wrangler.toml	Cloudflare Workers config (3 envs)
docker-compose.yml	Local Postgres for tests
vitest.config.js	Test runner config

Documentation

7 rule files in .claude/rules/, 9 docs in docs/:

08-admin-docs.md - Admin documentation access
09-secrets-reference.md - All secrets with setup instructions

Admin Docs Architecture

Documentation is served via Worker at /docs, protected by auth. Pages projects are private storage backends.

Environment	Docs URL	Auth
Production	`/docs`	Admin session (TODO)
Staging	`/docs`	`X-Dev-Token`
Dev	`/docs`	`X-Dev-Token`
Preview	`/docs`	`X-Dev-Token`

Access: curl -H "X-Dev-Token: $TOKEN" https://app-api-preview.../docs

Full docs: See docs/08-admin-docs.md

Recommended Next Steps

Fix env fallbacks - Remove hardcoded values in src/db/index.js
Remove placeholder code - Delete init.sql items table
Implement auth flow - Per docs/03-setup.md gap analysis
Add metering annotations - @metered tags on DB-hitting routes
Set up Cloudflare Queue - For async usage tracking

Grep Cheat Sheet

Question	Command
DB queries	`rg "query\(env," src/`
Metered endpoints	`rg "@metered" src/`
All controllers	`rg -g "*.controller.js" ""`
Env var usage	`rg "env\.\w+" src/`
Error throws	`rg "throw new Error" src/`