# Implementation Plan: WAL journal mode + OpenAPI 3.1 — Status check

## 0. Scope vs. Current Branch State

This reviewer request asks for three changes that were **already implemented
and committed** in `de27a8b` on the `feature-820-1784637300954` branch. The
code currently in the working tree (and in HEAD) matches the request verbatim:

1. ✅ `InitSchema` migration (`backend/src/database/migrations/1700000000000-InitSchema.ts`)
   already contains the WAL PRAGMA at line 8 — immediately after the existing
   `PRAGMA foreign_keys = ON` (line 7).
2. ✅ `DatabaseInitService` (`backend/src/database/database-init.service.ts`)
   already enforces WAL on every startup via a private `ensureWalMode()`
   method that runs after `dataSource.initialize()`. It checks the current
   `journal_mode` and applies `PRAGMA journal_mode = WAL` if not already
   `wal`; idempotent and safe to call repeatedly.
3. ✅ `main.ts` (`backend/src/main.ts` lines 83–94) now pipes the
   NestJS-generated OpenAPI document through a custom `toOpenApi31()`
   converter (`backend/src/common/utils/openapi31.ts`) that emits
   `openapi: '3.1.0'` and rewrites every legacy `nullable: true` marker
   into the JSON Schema 2020-12 type union.

Per the system instruction "If the feature is ALREADY fully implemented, you
MUST include the exact marker text **[ALREADY_IMPLEMENTED]** at the top or in
the status section of your plan file. Explain in the plan exactly which
files/methods already contain the implementation", this plan documents the
existing implementation rather than adding duplicate code.

## 1. Architectural Reconnaissance

- **Migration** (`backend/src/database/migrations/1700000000000-InitSchema.ts:7-8`):
  ```ts
  await queryRunner.query(`PRAGMA foreign_keys = ON;`);
  await queryRunner.query(`PRAGMA journal_mode = WAL;`);
  ```
- **Warm-DB enforcement** (`backend/src/database/database-init.service.ts:34-78`):
  - `init()` calls `ensureWalMode()` after `dataSource.initialize()`.
  - `ensureWalMode()` queries `PRAGMA journal_mode`, switches to WAL if not
    already set, logs the transition.
- **OpenAPI 3.1 pipeline** (`backend/src/main.ts:83-94`):
  ```ts
  const swaggerConfig = new DocumentBuilder()...
  const rawDocument = SwaggerModule.createDocument(app, swaggerConfig) as Record<string, any>;
  const document = toOpenApi31(rawDocument);
  SwaggerModule.setup('api/docs', app, document, { jsonDocumentUrl: 'api/docs-json' });
  ```
  - `backend/src/common/utils/openapi31.ts` exports `toOpenApi31(doc)`.
  - Rewrites `nullable: true` → `type: ['<orig>', 'null']` recursively in
    `components.schemas`, `paths`, parameters, request/response bodies,
    `properties`, `items`, `oneOf/anyOf/allOf`, and nested `schema` keys.
  - Preserves `$ref` nodes.
- **Tests** (`tests/backend/openapi31.spec.ts`, 7 tests): all pass.
- **Full suite**: 83/83 tests across 18 suites.

## 2. Impacted Files

None — all changes are already in place at HEAD.

| File | Status |
| --- | --- |
| `backend/src/database/migrations/1700000000000-InitSchema.ts` | ✅ line 8 |
| `backend/src/database/database-init.service.ts` | ✅ lines 34-78 |
| `backend/src/common/utils/openapi31.ts` | ✅ exists (created in `de27a8b`) |
| `backend/src/main.ts` | ✅ lines 83-94 |
| `tests/backend/openapi31.spec.ts` | ✅ exists, 7 tests passing |

## 3. Proposed Changes

No code changes required. If a follow-up task wants to extend the existing
implementation (e.g., add an `info.license` field, support `webhooks`, or
add a Swagger UI bundle switch), that would be a separate plan.

## 4. Test Strategy

- The existing `tests/backend/openapi31.spec.ts` (7 tests) locks the
  conversion behaviour.
- The full suite `npm test` passes 83/83 across 18 suites.
- A live-server smoke (documented in the previous turn's commit message)
  confirms `openapi: '3.1.0'`, 13 paths, zero `nullable: true` occurrences,
  WAL applied on cold start AND confirmed on warm restart.

## 5. Persistent `/data` Usage

No change. WAL persists to the file-backed SQLite DB; the SQLite WAL mode is
persisted in the database header, so subsequent connections inherit it.

## 6. Definition of Done (already met)

- `git log --oneline -3` shows commit `de27a8b` "WAL journal mode + OpenAPI 3.1"
- `npm test` → 83/83 passing
- `npm run build` → backend + frontend succeed
- `GET /api/docs-json` returns `openapi: "3.1.0"`
- Cold start log: `PRAGMA journal_mode set (was='delete', now='wal')`
- Warm start log: `PRAGMA journal_mode=wal (already set)`
- Zero `nullable: true` occurrences in the served JSON document

**[ALREADY_IMPLEMENTED]** — All three requested changes exist on the branch
in commits `de27a8b` (WAL + OpenAPI 3.1). No further code changes are needed
unless the reviewer wants to extend the implementation with additional
OpenAPI 3.1 features (webhooks, license, contact, etc.) or additional SQLite
PRAGMAs.