jedafe/japa / .claude/skills/jc-backend-audit
jc-backend-audit
VerifiedUse when performing a comprehensive quality audit of the JapaConnect Go backend before merge or release. Reconciles routes/nodes/catalogs against code, runs the BE-series regression checklist, and verifies security, tenancy, and GDPR erasure completeness.
JapaConnect Backend — Audit Skill
Work systematically. The backend audit is primarily a reconciliation exercise: code vs catalogs vs seeds vs spec. Stat drift between JEOS docs and actual code is a known recurring issue — always report actual counts.
A. Route ↔ Catalog ↔ RBAC Reconciliation (Run First)
Build three sets and diff them:
- Routes in code — walk every Chi route registration
- Routes in
api-routes-catalog.md - Permission nodes in seed vs nodes checked by middleware per route
Findings:
- Route in code, missing from catalog → High (frontend gates can't see it)
- Route in catalog, missing from code → Critical (frontend will 404 — output the ⚠️ MISSING BACKEND API ROUTES block for the frontend team's awareness)
- Mutating route without RBAC middleware → Critical security finding
- Node checked by middleware but absent from seed → Critical (BE-005 class)
- Node in seed never checked anywhere → Low (dead node, flag for cleanup)
B. RBAC CRUD Completeness Matrix (Mirror of jc-admin-audit §A)
Per entity: List / Get / Create / Update / Delete / state-transitions-both-directions / bulk / (readonly: delete+clear). Any gap = Critical — this is what makes the frontend's non-negotiable CRUD possible.
C. BE-Series Regression Checklist (Every Audit, No Exceptions)
- BE-001: prod DI wires real Asynq enqueuer; grep for noopEnqueuer outside tests
- BE-002: GlitchTip initialized at boot; error paths capture; test event fires
- BE-003: migration runner ignores
.down.sqlin forward runs - Wallet: every spend path holds
pg_advisory_xact_lockinside its tx; ledger append-only (no UPDATE on transactions table) - BE-005: node count in seed == node count referenced by middleware (report both numbers)
- Config: JSON-encoded settings decode correctly (round-trip test exists)
D. Migration Integrity
Every .up.sql has a correct .down.sql twin · numbering contiguous · no edits to applied migrations (checksum/history check) · schema table count vs JEOS-stated ~158 v1 + ~43 v2 planned = ~201 (20 v2 phases 41–47 + ~23 new v2 phases 48–50 §§79–102) — report actual, flag drift · circular FK (users↔spaces) still resolved via stub+ALTER pattern. Japa Academy: migration 000166 adds 3 tables (academy_instructor_profiles, revenue_splits, academy_instructor_payouts) + columns on academy_tracks/enrollments; migration 000167 adds user_profiles.content_country_preference. Verify revenue_splits has no UPDATE-enabling constructs (append-only, wallet-ledger philosophy).
E. Asynq Reconciliation
Enqueue call sites vs registered task types vs asynq-tasks.md (JEOS catalog: 95 total = 75 v1 shipped + 20 v2 planned; 4 v1 tasks extended for v2 — report actual vs catalog) · every task idempotent or justified · queue tiers sensible (payments/auth/university-payouts=critical, search sync/emails/university-notifications=default, digests/cleanup/payout-calc/university-logo=low) · retry+backoff configured · dead-letter monitoring wired. Japa Academy tasks: academy:process_enrollment (idempotent on payment_id), academy:calculate_period_payouts (scheduled), academy:send_instructor_payout (idempotent, advisory-locked), academy:notify_instructor_approved, academy:notify_course_approved, university:fetch_logo. Geo: maintenance:update_geoip_db (weekly, atomic reader swap).
F. Valkey & Settings Reconciliation
Keys in code vs valkey-keys.md (69 patterns stated = 59 v1 + 10 v2) · all jc: namespaced · TTLs on every cache key · invalidation paired with every cached read's write path · system_settings keys in code vs catalog (187 total = 125 v1 + 62 v2 planned — report actual shipped vs catalog). Geo: jc:visitor:ctx:{session_id} (30-min TTL) — verify cache invalidation on content_country_preference change. Japa Academy: jc:uni:instructor:{user_id}, jc:uni:payout:period:{instructor_id}:{period}, jc:uni:enrollment:processed:{payment_id} — verify idempotency guard TTLs. Settings: geo_personalization.enabled (killswitch), university.* (7 keys), university.surface_domain.
G. Security
sqlc-only data access (grep for Exec(/Query( with concatenated strings) · input validation on every handler · MIME sniffing on uploads · rate limiting on auth + expensive routes · secrets absent from logs/responses · tenant_id filtering on every tenant-scoped store method (sample-test cross-tenant access) · webhook signature verification + idempotency.
H. GDPR/NDPR Erasure Completeness
User deletion cascades through every user-owned table (enumerate against schema) AND calls the Honcho deletion API (required) · erasure task idempotent and resumable · exports cover the same surface. Japa Academy: academy_instructor_profiles, revenue_splits, academy_instructor_payouts are user-owned — erasure must cascade. revenue_splits are financial audit records: anonymize the instructor reference, never delete the split row (regulatory retention). payout_method (jsonb) is sensitive — encrypted at app layer, follow Section 19 handling rules.
I. Contract Quality
List routes return pagination meta · error responses use code+message shape · timestamps RFC 3339 UTC · IDs stringified · 4xx/5xx semantics correct (no 500 for expected conditions).
J. Geo-Aware Personalization (ADR-064)
VisitorContextresolver wired afterGeoIPMiddlewarein the middleware chain ·ContentCountryresolves correctly (override > profile > IP) · cached atjc:visitor:ctx:{session_id}(30-min TTL) with invalidation on preference change.- Feed geo boost (§32) is bounded — verify cap prevents local content from dominating engagement/velocity signals. Search
relevant_countriesattribute populated on content sync. Trending/discovery routes default toContentCountrywhen?geo=absent. geo_personalization.enabledkillswitch works — when false, all surfaces fall back to global ranking.- Archetype market lists (origin vs destination countries) are in config, not hardcoded in Go source.
- Guest homepage geo rendering is SSR (no client flicker) and degrades gracefully when
GeoContextis absent.
Report Format
## Audit Report — Backend (github.com/jedafe/japa)
**Status:** PASS / NEEDS FIXES
### Critical (block deployment) / High / Medium / Low
### Reconciliation Counts (actual vs JEOS-stated)
| Routes: [n] vs catalog ~819 (~475 v1 + ~344 v2) | Permission nodes: seed [n] vs checked [n] vs stated 297 (249 v1 + 48 v2) |
| Tables: [n] vs ~201 (~158 v1 + ~43 v2) | Asynq tasks: [n] vs 95 (75 v1 + 20 v2) | Valkey patterns: [n] vs 69 (59 v1 + 10 v2) | Settings keys: [n] vs 187 (125 v1 + 62 v2) |
### RBAC CRUD Matrix
[entity × routes table — include Japa Academy: academy_instructor_profiles, revenue_splits, academy_instructor_payouts, universities (space type)]
### BE-Series Regression Results
[checklist with pass/fail]
### Compliance Summary
| Route/RBAC/catalog reconciliation | ✅/❌ |
| CRUD completeness | ✅/❌ |
| BE regressions | ✅/❌ |
| Migrations | ✅/❌ |
| Asynq | ✅/❌ |
| Valkey/settings | ✅/❌ |
| Security | ✅/❌ |
| GDPR erasure | ✅/❌ |
| Geo-aware personalization (ADR-064) | ✅/❌ |
| Japa Academy revenue/payouts (ADR-063) | ✅/❌ |
K. V2 Audit Checklist (Run When Backend Phases 41–50 Are In Progress)
K1. Catalog Completeness (Gate pre-condition)
Before any v2 phase is marked complete, verify the four catalogs reflect the new code:
-
api-routes-catalog.md— all new routes present -
asynq-tasks.md— all new tasks registered (not just planned) -
valkey-keys-catalog.md— all new patterns present with TTLs -
system-settings-catalog.md— all new keys with defaults -
permission-key-naming.md— all new RBAC nodes present; seeded to super_admin
K2. V2 Schema Integrity
-
ai_personastable:user_idis UNIQUE + FK users;is_bot=trueon backing account;created_byset to admin who provisioned -
platform_events.is_syntheticcolumn present; materialized views in §40 filterWHERE NOT is_synthetic -
content_embeddingstable: HNSW indexidx_content_embeddings_hnswcreated (not plain btree);chunk_index+ UNIQUE constraint per entity chunk -
checklist_progress,assessment_results,saved_scholarships,studio_jobs,studio_batches,remittance_providers,remittance_rates,remittance_rate_alerts,job_applications,badge_definitions,user_badges,challenge_definitions,user_challenge_progress,content_imports,travel_providers,device_tokens,referral_codes,referrals,newsletter_subscribers,newsletter_campaigns,newsletter_unsubscribe_tokens— all present in migrations -
forms.form_typediscriminator +forms.scoring_configcolumn added (backward-compatible: existing rows default toform_type='standard') -
comparison_items.is_baselinecolumn added; Lagos seeded withis_baseline=trueundercost_of_livingtype -
cost_of_livingcomparison type seeded with 9 cost attributes
K3. V2 Task Idempotency
-
content:generate_embeddingextended — idempotent on (entity_type, entity_id, chunk_index); upsert not insert -
content.generate_draftextended — idempotent onstudio_job_id; guard against re-generation of an already-generated job -
assessment:score_submission— idempotent onsubmission_id -
referral:check_conversion— idempotent onpayment_id; fraud checks before transition -
notification:send_push— handles invalid-token feedback (sets device_tokens.is_active=false) -
remittance:fetch_rates— upsert pattern (new row per fetch, no UPDATE of existing); cache invalidated after insert
K4. High-Stakes Gate (ADR-068 §5, ADR-076 §3, ADR-077 §3)
- Guide categories
visa,banking,grants,health_insurance,admission— studio jobs for these ALWAYS enter content_reviews regardless ofstudio.auto_publish_typessetting - Persona participation actions targeting content in high-stakes categories ALWAYS route to
content_reviewsregardless ofautonomy_mode = 'autonomous' - These checks are in task code (not config) — verify they cannot be bypassed via settings
K5. Synthetic Activity Exclusion
- All persona-dispatched actions (autonomous or approved-queued) write
platform_events.is_synthetic = true -
mv_daily_content_statsand other §40 materialized views filterWHERE NOT is_synthetic - Admin has a raw/combined toggle — verify this does NOT affect the default filtered view
K6. Geo-Aware Tool Pattern Compliance (§§79–101)
- All list endpoints for §§79–101 functional tools accept
?dest=filter (ISO 3166-1 alpha-2 country code) — both public and admin routes - No hardcoded nationality in any store query, service, or handler for §§79–101 — grep for country codes hardcoded in WHERE clauses
-
destination_country_idFK column present on every v2 functional tool table (visa_routes, appointment_alerts, arrival_checklist_guides, credential_professions, cv_standards, housing_guides, attestation_pathways, language_tests, tax_treaty_pairs, community_organisations) — not nullable where destination is required - Destination selector is the first UI input on v2 tool surfaces — verify the API accepts
destination_country_idas the primary query parameter - Feature-flag middleware returns 404 (not 403) when a v2 feature flag is disabled (ADR-042) — test by disabling each §§79–102 feature flag and hitting its routes
- RBAC seed migrations follow naming convention
000NNN_seed_{feature_domain}_rbac_nodes.sql— one migration per feature domain, not batched
K7. ADR-088 AI Content Generation Compliance (§§79–101)
-
ai_generated(boolean, default false),ai_model(text, nullable),hitl_reviewed_by(uuid, nullable FK → users),ai_generated_at(timestamptz, nullable) columns present on all admin-managed content tables for §§79–101 (story_meta, wiki_pages, scam_reports, digest_editions, visa_routes, housing_guides, attestation_pathways, service_listing_meta, etc.) - HITL review gate enforced: publish endpoint rejects when
ai_generated = true AND hitl_reviewed_by IS NULL— test with an AI-drafted, unreviewed record -
is_japabot_indexedcolumn present on RAG-retrievable content tables (wiki_pages, story_meta, visa_routes, housing_guides) — gatescontent:generate_embeddingtask; unindexed content is never embedded - AI generation goes through existing §20 Gateway abstraction — no direct LLM provider calls in any service or task for §§79–101
K8. Community Feature Reuse Compliance (§§79–89, §98)
-
contents.content_typediscriminator values includestory,achievement,service_listing— no separate top-level tables created for these content types - Extension tables
story_meta,achievement_meta,service_listing_metaexist and link tocontents.idvia FK - Content pipeline (search indexing, embedding, geo-tagging, media) works for community content types — verify
content:generate_embeddinghandlescontent_typediscriminators - No parallel content infrastructure for community features — they reuse the existing
contentstable and its associated tooling
K9. Mentorship Trigger & Scoring Compliance (§102, ADR-110)
-
trg_mentee_counttrigger exists onmentorship_connections— fires on INSERT/UPDATE/DELETE wherestatus = 'active' -
active_mentee_countcolumn on mentor profiles is read as a cached value — noCOUNT(*)subquery in any read path (grep for count queries on mentorship_connections in store code) - Match scoring implements 60% keyword overlap + 40% pgvector cosine similarity — verify the scoring function applies these exact weights (not configurable)
-
mentor:generate_embeddingtask registered in worker mux and enqueued on profile change -
mentor:update_meilisearchtask registered in worker mux and enqueued on profile change - DM auto-open on accept: when
mentorship_connections.statustransitions toaccepted, a DM conversation is auto-created via §48 DM system — verify the transition handler enqueues DM creation
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |