08-Project-Health / 08.01.Audit-Findings

08.01.Audit Findings

08.01. Audit Findings

This audit was performed autonomously to verify the consistency between the source code and documentation, and to identify areas for improvement following IT Best Practices.

1. Top 30+ Observations (Inconsistencies, Bugs, Questions, Improvements)

Critical & Potential Bugs

  1. Duplicate Route Definition: In tesla.py, the endpoint generate_vehicle_report_pdf_async (path /vehicle-report/pdf/async) is defined twice. One implementation uses Cloud Tasks, while the other uses FastAPI BackgroundTasks. This causes a conflict in the routing table.
  2. Pricing Model Mismatch: config.py contains two pricing structures: PAYMENT_PLANS (fixed 19/29/149 EUR) and TIER_TABLE (tiered 9.99/19.99/29.99 EUR). The WUI uses the tiered model via /catalog, but some backend paths might still reference the legacy fixed plans.
  3. HSTS in Dev: HSTS_MAX_AGE is set to 1 year in config.py. While secure, it can cause issues during local development if HTTPS is not consistently used across all tools.
  4. CSP Header Hardcoding: Content Security Policy headers are hardcoded in app/main.py. These should be moved to config.py to allow environment-specific overrides (e.g., allowing local dev tools).
  5. Voucher Race Condition: main.py bootstraps voucher usage on startup. In a multi-instance Cloud Run environment, this logic should be coordinated via a Redis lock or a single source of truth.
  6. Hardcoded Frontend URL: FRONTEND_URL in config.py defaults to production. This breaks local OAuth callback flow if the .env override is missing.
  7. PDF Cleanup Conflict: PDF_CLEANUP_DELAY_SECONDS is set to 60s, but the new Puppeteer spec mentions a 30-minute lifecycle. This requires reconciliation.
  8. Trace Secret Management: TRACE_SECRET is used for selective tracing but is not clearly documented as a secret that needs rotation in 029-create-gcp-secrets.
  9. Tesla Region Bias: The system defaults to EU for Tesla Fleet API. While supported, NA/CN regions require manual env overrides rather than auto-detection or user selection.
  10. Admin Auth: ADMIN_USERNAME and ADMIN_PASSWORD_HASH are optional and default to None. This leaves admin paths potentially unprotected or unusable without explicit configuration.

Documentation Inconsistencies

  1. Documentation Duplication: Documentation was heavily duplicated between sub-modules and bnc-cpt-doc. (Resolved via refactor).
  2. Outdated READMEs: Top-level README.md files in sub-modules often list older endpoint patterns (v1) instead of the current session-based (v2) flow.
  3. Local Port Confusion: WUI port is listed as 3333 in some docs but 8080 in Makefiles/Compose.
  4. Stripe API Key naming: Some docs refer to STRIPE_API_KEY while the code exclusively uses STRIPE_SECRET_KEY.
  5. Shadow Route Mystery: The isShadowReportRoute logic in App.vue and its associated components are not mentioned in the architectural overview.
  6. VITE_API_BASE_URL: Used as /api in dev, but its relationship with production Nginx routing is not explicitly documented.
  7. CORS Configuration: CORS_ORIGINS in dev.env.yaml might be too restrictive for certain developer setups (e.g., mobile testing).
  8. GCP Project Mapping: The mechanism for deriving GCP_PROJECT for Cloud Tasks when the env var is empty is implicit and potentially error-prone.
  9. Testing instructions: the-bot instructions in GEMINI.md mention npm test inside the container, but the Makefile has different wrappers.
  10. Product Roadmap Sync: PRODUCT-ROADMAP-v2.md lists features that are already implemented, making it unclear what is actually "Next Steps".

Open Questions

  1. Database Strategy: When is the transition from "placeholder" Redis storage to a persistent RDBMS (Postgres) planned?
  2. Payment Timeline: What is the priority for implementing Google Pay, Apple Pay, and MobilePay placeholders?
  3. User Identity: Will there be a transition from "Session-Only" to "Persistent User Accounts"?
  4. Tesla Fleet Public Key: Is the endpoint /.well-known/... being correctly served in all environments for Tesla partner verification?
  5. Rate Limit Calibration: Are the current limits (e.g., 10/min for payments) based on real-world load testing or safe defaults?
  6. Localized Content Completion: Which of the 9 languages are considered "Production Ready"?
  7. GCS Rate Limits: Does the cleanup task handle potential GCP rate limits during high-volume object deletion?
  8. Voucher Validation logic: Does the system support expiration dates or usage limits beyond the simple existence check?
  9. VPC Connector Necessity: Is the VPC connector strictly required for internal-only Cloud Run services if they don't reach Redis/DB? (Confirmed: yes for Redis).
  10. Artifact Registry Costs: Is there a policy for pruning old images beyond the current Terraform cleanup rules?

Improvements & IT Best Practices

  1. Centralized Doc Hub: (Completed) Consolidation of docs into logical units (Arch, Dev, Ops, Product).
  2. Swagger Completeness: Backend endpoints need better Pydantic examples and descriptions for better auto-generated docs.
  3. Automated Doc Sync: A pre-commit hook or CI check should ensure bnc-cpt-doc stays updated with code changes.
  4. Redis Namespacing: Move from simple prefixes to a hierarchical namespace (e.g., bnc:cpt:dev:task).
  5. Makefile Categorization: Reorganize make help output into functional categories.

2. Refactoring Summary

New Taxonomy

Master Files Created/Updated

Audit completed by Gemini CLI