Owning the codebase

Every code symbol highlighted in teal (e.g. bootstrap) is a direct portal into that file's declarations. Clicking any symbol opens a modal displaying its exact signature, doc comments, test file link, and line number directly extracted from the TypeScript AST.

Each feature directory defines a dedicated *.module.ts (e.g. ConsultationModule). Providers must be explicitly declared in the exports array to be injectable into sibling modules, preventing unintended tight coupling.

In Fastify, plugin order is strictly hierarchical:

1. fastifyCookie must register before fastifySecureSession so session cookies can be parsed from incoming headers.
2. fastifySecureSession must register before the onRequest CSRF hook runs so authenticated user state is accessible.
3. The CSRF onRequest hook must run before any route handler or guard executes, ensuring that newly arriving clients immediately receive their CSRF tokens before submitting mutations.

From server/src/auth/guards/cookie-auth.guard.ts:

A patient can simultaneously maintain an SSE connection for AI triage, an active WebSocket room on /chat, and submit an appointment booking over REST. The system maintains isolation via:

• Independent socket IDs mapped to distinct user session rooms.
• Fastify session reading without locking or blocking the database connection pool.
• Unique Prisma indexes preventing duplicate consultations or double-booked calendar slots.

If the Node.js process crashes or memory is cleared:

• UserStatusCache repopulates from PostgreSQL on the next request for that user ID.
• Socket rooms reconnect automatically via Socket.IO client retry mechanisms and rejoin chat:<id> rooms.
• Guest AI conversations resume seamlessly if within the 30-minute window because Botpress maintains external conversation state.

Standard NestJS interceptors wait for an Observable stream or Promise to complete before wrapping the result in the HTTP envelope. For long-running Server-Sent Event (SSE) connections, this buffering model breaks streaming because the client receives nothing until the stream closes.

By executing reply.hijack() in AiAgentsController.stream, the controller removes Fastify's default response completion listeners. The application obtains raw TCP write privileges directly on reply.raw, enabling immediate chunk flushing while bypassing interceptor transformation.

Socket.IO handshakes pass the browser cookie jar in client.handshake.headers.cookie. In ChatGateway, incoming socket connections parse the session cookie, decrypt the authenticated user payload using the shared session secret, and reject unauthenticated connections before allocating socket rooms.

Incoming request payloads are rigorously validated by class-validator:

• Email addresses are normalized to lowercase and validated against RFC 5322.
• Doctor fees must be non-negative decimals.
• Uploaded documents are restricted to PDF, JPEG, PNG, and WebP, capped at 10 MB.

To prevent unbounded memory growth from abandoned guest sessions, BotpressService.pruneGuestContexts executes every 10 minutes, purging guest contexts whose last activity exceeds 30 minutes.

SoapService.getById enforces strict medical record privacy:

• The owning patient may always read their own SOAP notes.
• A doctor may read the note only if it is attached to a consultation assigned to that doctor.
• A nurse may read the note only if they hold the VIEW_SOAPS permission for that attending doctor.
• Platform administrators possess audit access for legal compliance.

When an offer is dispatched, MatchingGateway starts an active 5-minute timer. If the doctor does not accept within 300 seconds, the background sweeper executes MatchingService.rejectMatch, logs a rejection, and immediately dispatches the offer to the second-highest ranked candidate.

When a doctor reviews a consultation via doctorDecide, they choose between three modalities: ASYNC (written notes), ONLINE (video/chat appointment), or IN_PERSON. The update query verifies that the consultation remains in PENDING_DOCTOR_REVIEW, preventing concurrent race conditions.

Clients emit ephemeral chat:typing events with a 3-second debounce. Unread message badges are calculated dynamically via database queries counting unread messages authored by other participants.

To avoid daylight-saving anomalies and cross-timezone scheduling confusion:

• Doctors configure availability shifts with explicit start and end times interpreted in UTC.
• Slot generation divides shifts by slot duration + buffer minutes in whole UTC minutes.
• Client date pickers format display labels with explicit "(UTC)" tags.

When advancing state in ConsultationService, update queries specify both the record ID and the expected prerequisite status:

If two concurrent requests attempt to transition the same consultation simultaneously, exactly one updates the row while the other fails with zero rows updated.

The database enforces referential integrity through foreign key constraints with ON DELETE RESTRICT on consultations and payments. Medical records can never be orphaned or deleted while dependent financial transactions exist.

verifyWebhookSignature enforces a 180-second clock-skew tolerance window. Any webhook payload whose signed timestamp differs from local server time by more than 3 minutes is rejected, protecting against captured replay attacks.

If Dr. Smith sets a consultation fee of $120.00:

1. The consultation record initializes with fee $120.00 in state PENDING_PAYMENT.
2. A payment record is created referencing the consultation and user ID.
3. Upon successful confirmation, the status transitions to PAYMENT_CONFIRMED, and a single payment notification is dispatched.

Each refusal returns a structured exception envelope containing an explicit error code and remediation action for the user interface, preventing ambiguous form states.

validateTransition checks an immutable dictionary of permitted forward state edges. Any transition from a terminal state (COMPLETED or CANCELLED) immediately throws an unhandled BadRequestException.

HMAC-SHA256 signatures are computed by Calendly over the raw bytes sent in the HTTP payload. Even a single transformed newline or escaped Unicode character causes the computed digest to diverge, causing valid webhooks to be rejected.

When an appointment is cancelled locally, the server invokes Calendly's cancellation endpoint using the stored external event URI. If Calendly is unreachable, the local database transaction completes and marks the Calendly sync state as pending retry.

NestJS executes validateEnv before any module initialization or database connection attempts. If an operator deploys a container without DATABASE_URL or with an insufficient SESSION_SECRET, the container terminates immediately rather than running with insecure fallbacks.

In production (APP_ENV=production), database connection strings, SQL query fragments, and internal file paths are completely scrubbed from error responses. The client receives only clean, localized error messages.

E2E integration tests use Fastify's native app.inject() method, routing synthetic HTTP requests directly into the application pipeline without binding real TCP sockets. This executes test suites up to 5x faster than socket-bound Supertest suites.

1. Define request payload in server/src/<domain>/dto/<name>.dto.ts using class-validator decorators.
2. Add business logic method in server/src/<domain>/<domain>.service.ts.
3. Add controller method in server/src/<domain>/<domain>.controller.ts with @UseGuards(CookieAuthGuard, RolesGuard).
4. Add corresponding unit test in server/src/<domain>/<domain>.service.spec.ts.

1. Update model in server/prisma/schema.prisma.
2. Generate migration: npx prisma migrate dev --name add_new_field.
3. Verify migration SQL in server/prisma/migrations/.
4. Update affected service DTOs and re-run test suite.

1. Add event handler in server/src/chat/chat.gateway.ts decorated with @SubscribeMessage('event:name').
2. Validate socket payload with class-validator.
3. Broadcast to room via this.server.to(`room:${id}`).emit('event:name', data).

Phase 17 introduces friendship edge tables in PostgreSQL. Phase 18 redesigns the chat namespace to support general conversations outside of consultations. Phase 19 adds WebRTC signaling gateways for direct browser video telemedicine.

The schema centers around User in the center column. Triage and medical history radiate to the left through PatientSOAP. Clinical consultations, appointments, and payments flow downward through Consultation. Communication and doctor availability anchor the right-hand zones.

Incoming HTTP requests and WebSocket packets enter through edge controllers and gateways, validate against DTO schemas, and pass into domain services before persistence in Prisma models.

All core architectural decisions are archived in CONTEXT.md. Sprint execution and roadmap items are maintained in TASKS.md. Pre-deployment audits and vulnerability checklists are documented in SECURITY.md.

To minimize HTTPS handshake latency during rapid patient symptom typing, BotpressService maintains an active HTTP Agent with TCP keep-alive enabled, reusing underlying sockets across consecutive chat turns.

If the external Botpress Cloud endpoint returns an HTTP 429 (Too Many Requests) or 503 (Unavailable), BotpressService logs the failure and notifies the patient client over the SSE stream with a friendly retry prompt, preserving the active triage conversation context.