Prode: Elite Codebase Documentation Generator

language_and_stack: TypeScript, Node.js, Fastify, Prisma, PostgreSQL codebase_description: A REST API service that handles user authentication, subscription billing via Stripe, and webhook event processing for a SaaS product. ~8,000 lines across 40 files. target_audience: Mid-level backend engineers onboarding to the team documentation_scope: Full documentation including architecture, API reference, and onboarding guide

## Overview This service is the core backend API for the SaaS platform, responsible for three primary domains: user identity and authentication (JWT + refresh token rotation), subscription lifecycle management via Stripe, and inbound webhook processing from third-party integrations. It exposes a REST API consumed by the frontend and mobile clients, and is deployed as a single Node.js process on Railway. ## Architecture Diagram ``` Client (Web/Mobile) │ ▼ Fastify Router ┌───────────────────────────────┐ │ Auth Routes │ Billing │ Webhooks │ │ /auth/* │ /subscript* │ /webhooks/* │ └──────┬─────────┴──────┬───────┴──────┬────────┘ │ │ │ AuthService StripeService WebhookRouter │ │ │ Prisma ORM Stripe SDK Event Handlers │ PostgreSQL ``` ## Module Breakdown ### `src/services/AuthService.ts` **Purpose**: Manages registration, login, token issuance, and refresh token rotation. **Key exports**: `register()`, `login()`, `refreshTokens()`, `revokeSession()` **Dependencies**: `bcrypt`, `jsonwebtoken`, Prisma `User` and `Session` models **Caveats**: Refresh tokens are single-use and rotated on every call — storing the old token after refresh will result in a 401 on the next request. Sessions are invalidated server-side on logout; client must also clear local storage. ### `src/services/StripeService.ts` **Purpose**: Wraps Stripe SDK calls for subscription creation, cancellation, and plan upgrades. **Key exports**: `createSubscription()`, `cancelSubscription()`, `syncCustomer()` **Caveats**: `syncCustomer()` is idempotent and safe to call multiple times — use it after any Stripe webhook to ensure local state is consistent. ## Known Gotchas - Stripe webhook events arrive out of order. The `WebhookRouter` uses event timestamps to discard stale events — do not remove the `created` field check. - `refreshTokens()` will throw `TOKEN_FAMILY_COMPROMISED` if a reused token is detected. This invalidates the entire session family by design (reuse detection). - [NEEDS CLARIFICATION: The `src/jobs/` directory contains three cron jobs but they are not documented in any existing README — ownership and schedules need confirmation from the team.]