Skip to content

feat: infrastructure hardening, tailwind 4 migration, and ai type-safety #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
EmiyaKiritsugu3 merged 15 commits into from
Apr 11, 2026
Merged

feat: infrastructure hardening, tailwind 4 migration, and ai type-safety #61

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
c372f60
feat(telemetry): modernize Sentry v10 + Next.js 15 for stability
EmiyaKiritsugu3 Apr 11, 2026
c7f2e7a
fix(lint): repair typescript-eslint flat config for production build
EmiyaKiritsugu3 Apr 11, 2026
615986a
feat(auth): link Supabase User context to Sentry coverage
EmiyaKiritsugu3 Apr 11, 2026
58e0e7a
docs(sentry): sync documentation with finalized smartmanagementesyste…
EmiyaKiritsugu3 Apr 11, 2026
1322994
feat(sentry): link project to smartmanagementesystem and modernize co…
EmiyaKiritsugu3 Apr 11, 2026
557c6a7
refactor(sentry): move client config to instrumentation-client.ts
EmiyaKiritsugu3 Apr 11, 2026
e56c38d
docs(sentry): document Vercel CI/CD integration and fix SLO formatting
EmiyaKiritsugu3 Apr 11, 2026
8f77d1d
feat(observability): harden Sentry PII scrubbing and replay privacy
EmiyaKiritsugu3 Apr 11, 2026
0feb172
fix(boot): implement resilient database heartbeat timeout
EmiyaKiritsugu3 Apr 11, 2026
ddeb432
fix(boot): implement resilient database heartbeat timeout
EmiyaKiritsugu3 Apr 11, 2026
e17005f
feat(observability): enhance sentry pii scrubbing with cycle protection
EmiyaKiritsugu3 Apr 11, 2026
d48363c
feat(design): migrate to tailwind 4 with unified oklch theme
EmiyaKiritsugu3 Apr 11, 2026
7026de0
refactor(ai): ensure strict type safety for genkit flows and frontend
EmiyaKiritsugu3 Apr 11, 2026
3f3d4d3
docs(architecture): finalize adr-003 for infra hardening and design
EmiyaKiritsugu3 Apr 11, 2026
285948c
docs(governance): update technical debt and project state
EmiyaKiritsugu3 Apr 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ GITHUB_TOKEN=
# --------------------------------------------

# Sentry (error tracking)
# Get from sentry.io → Project → Settings → Client Keys
# Get from sentry.io → Project → Settings → Cli# Sentry Observability (smartmanagementesystem: ufrn-universidade-federal-do-r)

@coderabbitai coderabbitai Bot Apr 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix the malformed Sentry setup guidance comment.

Line 63 currently merges two notes (Cli# ...) and is easy to misread when setting NEXT_PUBLIC_SENTRY_DSN vs SENTRY_AUTH_TOKEN.

Suggested doc fix 
-# Get from sentry.io → Project → Settings → Cli# Sentry Observability (smartmanagementesystem: ufrn-universidade-federal-do-r)
+# DSN: sentry.io → Project Settings → Client Keys (DSN)
+# Auth token: sentry.io → Organization Settings → Auth Tokens
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# Get from sentry.io → Project → Settings → Cli# Sentry Observability (smartmanagementesystem: ufrn-universidade-federal-do-r)
# DSN: sentry.io → Project Settings → Client Keys (DSN)
# Auth token: sentry.io → Organization Settings → Auth Tokens
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.env.example at line 63, Update the malformed comment on line 63 to clearly
separate instructions for NEXT_PUBLIC_SENTRY_DSN and SENTRY_AUTH_TOKEN: replace
the merged note ("Cli# Sentry Observability...") with two concise guidance lines
indicating where to obtain each value (e.g., "NEXT_PUBLIC_SENTRY_DSN: get from
Sentry → Project → Settings → Client Keys / DSN" and "SENTRY_AUTH_TOKEN: get
from Sentry → Settings → API Keys or Auth Tokens"), and remove the truncated
project identifier so the comment reads unambiguous guidance for
NEXT_PUBLIC_SENTRY_DSN and SENTRY_AUTH_TOKEN.

NEXT_PUBLIC_SENTRY_DSN=
SENTRY_AUTH_TOKEN=
SENTRY_ENVIRONMENT=production
Expand Down
7 changes: 7 additions & 0 deletions .sentryclirc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
[defaults]
org=ufrn-universidade-federal-do-r
project=smartmanagementesystem

[auth]
# Note: The auth token is usually provided via SENTRY_AUTH_TOKEN env var in CI.
# If running locally, you can run 'sentry-cli login'.
20 changes: 20 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased] — 2026-04-11 — Sentry & Build Stability

### Added

- **Sentry v10 Modernization**: migrated to Next.js 15 standards using `src/instrumentation-client.ts` for navigation tracing.
- **Deep PII Scrubbing**: implemented a recursive sanitization engine in `sentry.server.config.ts` to protect student data (CPF, health hashes) in server logs.
- **Privacy-First Replays**: enabled Sentry Replay with strict `maskAllInputs: true` and `maskAllText: true` to prevent PII leakage.
- **DB Connection Heartbeat**: added a surgical `SELECT 1` check in `instrumentation.ts` to verify database health on application boot.
- **Full-stack User Traceability**: linked Supabase UUID/Email to Sentry context on both client and server.
- **Vercel CI/CD Integration**: Linked Sentry to Vercel for automated environment variable synchronization and sourcemap deployments.

### Changed

- **Prisma 7 Type Elevation**: removed generic `as any` casts by pinning `@types/pg` to version `8.11.11` via package `overrides`.
- **Database Pool Governance**: implemented `max: 20`, `idleTimeout`, and `connectionTimeout` in `src/lib/prisma.ts` for improved resilience.

### Fixed

- **ESLint Flat Config**: repaired missing `@typescript-eslint` plugin and parser configuration in `eslint.config.mjs` that was breaking production builds.

Comment on lines +8 to +27

@coderabbitai coderabbitai Bot Apr 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Consolidate duplicate Unreleased sections.

This adds another Unreleased block while the file already has multiple existing ones. Please keep a single Unreleased section and move older entries under dated/versioned headings.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CHANGELOG.md` around lines 8 - 27, The changelog contains a duplicate
"Unreleased" section (e.g., the header "## [Unreleased] — 2026-04-11 — Sentry &
Build Stability"); consolidate by keeping a single "Unreleased" heading and
merging these new entries into that section, and move any older or
previously-unreleased entries into dated/versioned headings below (creating or
updating versioned headers as needed) so there is only one Unreleased block in
the file.

## [0.4.0] — 2026-04-10 — Elite Workflow Setup (004)

### Added
Expand Down
5 changes: 3 additions & 2 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# PWeb_Project Development Guidelines

Auto-generated from all feature plans. Last updated: 2026-04-10
Auto-generated from all feature plans. Last updated: 2026-04-11

## Active Technologies

- TypeScript 5 (strict mode, `useUnknownInCatchVariables`) + Node.js 20 + Next.js 15 App Router, Prisma 7, Supabase SSR, Zod 3, Genkit 1.31 (004-elite-workflow-setup)
- PostgreSQL via Prisma; local Supabase CLI for E2E (ports 54321/54322) (004-elite-workflow-setup)

- TypeScript 5 (strict mode) + Next.js 15, Playwright, @sentry/nextjs, Vitest (004-elite-workflow-setup)
- TypeScript 5 (strict mode) + Next.js 15, Playwright, @sentry/nextjs (v10), Vitest, instrumentation-client.ts (fix/telemetry-and-e2e-stability)
- PostgreSQL via Prisma (produção + branch de staging) (004-elite-workflow-setup)

- TypeScript 5 (strict mode) + Next.js 15 App Router, Supabase SSR (`@supabase/ssr`), Prisma 7, Zod 3 (003-002-us00-financial)
Expand Down Expand Up @@ -40,6 +40,7 @@ TypeScript 5 (strict mode, `useUnknownInCatchVariables` enabled): Follow standar
## Recent Changes

- 004-elite-workflow-setup: Added TypeScript 5 (strict mode, `useUnknownInCatchVariables`) + Node.js 20 + Next.js 15 App Router, Prisma 7, Supabase SSR, Zod 3, Genkit 1.31
- fix/telemetry-and-e2e-stability: Modernized Sentry to v10 + Next.js 15, implemented Privacy-First Replay, linked Supabase User IDs to observability, and repaired ESLint flat config.

- 004-elite-workflow-setup: Added TypeScript 5 (strict mode) + Next.js 15, Playwright, @sentry/nextjs, Vitest

Expand Down
2 changes: 1 addition & 1 deletion docs/.obsidian/graph.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,4 @@
"linkDistance": 250,
"scale": 0.19753086419753077,
"close": true
}
}
39 changes: 22 additions & 17 deletions docs/.obsidian/workspace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,28 +4,18 @@
"type": "split",
"children": [
{
"id": "aee62c2e7cdadf80",
"id": "ef3a367f18f4a73f",
"type": "tabs",
"children": [
{
"id": "bad7fb61f0dc5d1f",
"id": "7a54e2cabf4474d1",
"type": "leaf",
"state": {
"type": "graph",
"state": {},
"icon": "lucide-git-fork",
"title": "Graph view"
}
},
{
"id": "8171e32c308ccd3f",
"type": "leaf",
"state": {
"type": "smart-release-notes-view",
"state": {},
"icon": "file-text",
"title": "Release Notes"
}
}
]
}
Expand Down Expand Up @@ -201,8 +191,26 @@
"obsidian-textgenerator-plugin:Text Generator: Templates Packages Manager": false
}
},
"active": "bad7fb61f0dc5d1f",
"active": "7a54e2cabf4474d1",
"lastOpenFiles": [
"dev-errors.md",
"security/THREAT-MODEL.md",
"security",
"process/RFC-TEMPLATE.md",
"process/POSTMORTEM-TEMPLATE.md",
"process",
"operations/RUNBOOK.md",
"operations/INCIDENT-RESPONSE.md",
"operations",
"observability/SLOS.md",
"observability",
"decisions/INSIGHTS-CI-E2E-PIPELINE.md",
"DEFINITION-OF-DONE.md",
"CURRENT-STATE.md",
"archive/architecture/ANALYSIS.md",
"decisions/ADR-004-prisma-migration-governance.md",
"decisions/ADR-003-render-phase-sync.md",
"README.md",
"specs/specs/001-fix-type-safety-bugs/checklists/requirements.md",
"specs/specs/004-elite-workflow-setup/spec.md",
"specs/specs/004-elite-workflow-setup/research.md",
Expand All @@ -215,13 +223,10 @@
"specs/specs/003-002-us00-financial/plan.md",
"specs/specs/001-fix-type-safety-bugs/tasks.md",
"specs/specs/001-fix-type-safety-bugs/spec.md",
"specs/specs/001-fix-type-safety-bugs/research.md",
"specs/specs/001-fix-type-safety-bugs/quickstart.md",
"specs/specs/001-fix-type-safety-bugs/plan.md",
"specs/specs/001-fix-type-safety-bugs/checklists",
"specs/specs/004-elite-workflow-setup",
"specs/specs/003-002-us00-financial",
"specs/specs/001-fix-type-safety-bugs",
"specs/specs"
]
}
}
92 changes: 50 additions & 42 deletions docs/CURRENT-STATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,41 @@
# Current State — Five Star Academy

**Last Updated**: 2026-04-10
**Branch**: `004-elite-workflow-setup`
**Version**: 0.4.0 (pre-release)
**Last Updated**: 2026-04-11
**Branch**: `fix/telemetry-and-e2e-stability`
**Version**: 0.4.1 (pre-release)

## What Works Today

| Feature | Status | Notes |
| ------------------------------------------- | ---------- | ------------------------------ |
| Admin login | ✅ Working | Supabase Auth SSR |
| Student login (Portal do Aluno) | ✅ Working | Separate session |
| Admin dashboard | ✅ Working | GERENTE + RECEPCIONISTA |
| Financial routes (`/financeiro`, `/planos`) | ✅ Working | GERENTE-only gate |
| Student workout view | ✅ Working | `meus-treinos` |
| AI workout generator | ✅ Working | Genkit + Gemini |
| Student enrollment | ✅ Working | Admin creates aluno |
| Gamification (XP, streaks) | ✅ Working | Hook `use-workout-tracker` |
| Prisma migrations | ✅ Tracked | `prisma/migrations/` |
| ESLint quality gate | ✅ Done | 0 errors — `any` + unused vars |
| TypeScript typecheck | ✅ Clean | 0 errors (strict mode) |
| Unit tests | ✅ Passing | 18/18 (Vitest) |
| Ops documentation | ✅ Done | Runbook, SLOs, threat model |
| Process documentation | ✅ Done | RFC + Postmortem templates |
| Local E2E stack | ✅ Done | `supabase start` (Docker) |
| E2E seed script | ✅ Done | `prisma/seed-e2e.ts` (4 users) |
| Playwright E2E suite | ✅ Done | 15/15 passing |
| CI E2E job | ✅ Done | `.github/workflows/ci.yml` |
| Sentry error tracking | ✅ Done | SDK + MCP + CLI configurados |
| Feature | Status | Notes |
| ------------------------------------------- | ------------- | ------------------------------ |
| Admin login | ✅ Working | Supabase Auth SSR |
| Student login (Portal do Aluno) | ✅ Working | Separate session |
| Admin dashboard | ✅ Working | GERENTE + RECEPCIONISTA |
| Financial routes (`/financeiro`, `/planos`) | ✅ Working | GERENTE-only gate |
| Student workout view | ✅ Working | `meus-treinos` |
| AI workout generator | ✅ Working | Genkit + Gemini |
| Student enrollment | ✅ Working | Admin creates aluno |
| Gamification (XP, streaks) | ✅ Working | Hook `use-workout-tracker` |
| Prisma migrations | ✅ Tracked | `prisma/migrations/` |
| ESLint quality gate | ✅ Done | 0 errors — `any` + unused vars |
| TypeScript typecheck | ✅ Clean | 0 errors (strict mode) |
| Unit tests | ✅ Passing | 18/18 (Vitest) |
| Ops documentation | ✅ Done | Runbook, SLOs, threat model |
Comment on lines +20 to +23

@coderabbitai coderabbitai Bot Apr 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Sync reported counts across this document.

The updated values conflict with other sections (e.g., unit test total and warning counts). Please reconcile these numbers so readiness status is unambiguous.

Also applies to: 33-39

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/CURRENT-STATE.md` around lines 20 - 23, The table rows "ESLint quality
gate", "TypeScript typecheck", "Unit tests", and "Ops documentation" contain
counts that conflict with other sections (notably the unit test total/warning
counts shown elsewhere); update these entries so they match the source of truth
(CI/test runner and linter reports) and then search for and replace all other
occurrences of those same values (e.g., the unit test total and warning counts
in the other summary block) so every instance in the document is consistent;
verify "Unit tests" count and any warning/error counts are identical to the test
results and correct any mismatched numbers found in the other section
referenced.

| Process documentation | ✅ Done | RFC + Postmortem templates |
| Local E2E stack | ✅ Done | `supabase start` (Docker) |
| E2E seed script | ✅ Done | `prisma/seed-e2e.ts` (4 users) |
| Playwright E2E suite | ✅ Done | 15/15 passing |
| CI E2E job | ✅ Done | `.github/workflows/ci.yml` |
| Sentry error tracking | ✅ Modernized | Next.js 15, v10, User Context |

## What Is Incomplete

| Area | Gap | Priority |
| ------------- | -------------------------------------------------------------- | -------- |
| CI security | 3 moderate vulns in `@prisma/dev` (transitive, non-production) | P3 |
| Lint warnings | 31 `no-console` warnings remain (not errors) | P3 |
| GitHub secret | `SUPABASE_LOCAL_SERVICE_ROLE_KEY` must be set for CI seed step | P1 |
| Area | Gap | Priority |
| ------------- | ------------------------------------------------------------------ | -------- |
| CI security | 3 moderate vulns in `@prisma/dev` (transitive, awaiting upstream) | P3 |
| Lint warnings | 31 `no-console` warnings remain (accepted for server debug) | P3 |
| GitHub secret | `SUPABASE_LOCAL_SERVICE_ROLE_KEY` must be set for CI seed | P1 |
| Env Sync | Ensure `NEXT_PUBLIC_SENTRY_DSN` is set in production for scrubbing | P1 |

## Quality Gates (current status)

Expand Down Expand Up @@ -80,22 +81,29 @@ npm run e2e → ✅ 15/15 passing

## Phase Progress (004-elite-workflow-setup)

| Phase | Description | Status |
| ----- | --------------------------- | ----------- |
| 1–3 | Governance & constitution | ✅ Complete |
| 4 | Staging environment (local) | ✅ Complete |
| 5 | ESLint quality gates | ✅ Complete |
| 6 | Coverage thresholds | ✅ Complete |
| 7 | Playwright E2E | ✅ Complete |
| 8 | Sentry error tracking | ✅ Complete |
| 9 | Polish & PR | ✅ Complete |
| Phase | Description | Status |
| ----- | ------------------------------- | ----------- |
| 1–3 | Governance & constitution | ✅ Complete |
| 4 | Staging environment (local) | ✅ Complete |
| 5 | ESLint quality gates | ✅ Complete |
| 6 | Coverage thresholds | ✅ Complete |
| 7 | Playwright E2E | ✅ Complete |
| 8 | Sentry & Infra Hardening | ✅ Complete |
| 9 | Tailwind 4 & Type Safety Update | ✅ Complete |

## Technical Debt Governance

The following items are recognized as "Managed Debt" — intentional compromises for compatibility or performance:

1. **Sentry Boundary Casts**: Use of `any` in `beforeSend` (suppressed with `eslint-disable`) is required due to Sentry SDK interface rigidness.
2. **Server console.log**: 31 warnings in Server Actions are preserved to ensure minimal observability in the terminal during development.
3. **Prisma Type Overrides**: We use `@pg/types` pinning to resolve Prisma 7/Next 15 conflicts until `@prisma/adapter-pg` upstream fixes land.

@coderabbitai coderabbitai Bot Apr 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix dependency name typo in managed debt note.

Line [100] references @pg/types, but the pinning in this PR is for @types/pg.

Proposed fix 
-3. **Prisma Type Overrides**: We use `@pg/types` pinning to resolve Prisma 7/Next 15 conflicts until `@prisma/adapter-pg` upstream fixes land.
+3. **Prisma Type Overrides**: We use `@types/pg` pinning to resolve Prisma 7/Next 15 conflicts until `@prisma/adapter-pg` upstream fixes land.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
3. **Prisma Type Overrides**: We use `@pg/types` pinning to resolve Prisma 7/Next 15 conflicts until `@prisma/adapter-pg` upstream fixes land.
3. **Prisma Type Overrides**: We use `@types/pg` pinning to resolve Prisma 7/Next 15 conflicts until `@prisma/adapter-pg` upstream fixes land.
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)

[warning] 100-100: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/CURRENT-STATE.md` at line 100, Update the managed-debt note that
currently names the wrong package; replace the incorrect package token
`@pg/types` with the correct dependency name `@types/pg` in the sentence
describing Prisma Type Overrides (the note referencing pinning to resolve Prisma
7/Next 15 conflicts) so the documentation matches the actual pin in this PR.


## Known Issues

- 31 `no-console` warnings in server actions and `data.ts` — accepted for now (server-side debug logging)
- `SUPABASE_LOCAL_ANON_KEY` GitHub Actions secret must be set before CI E2E job runs (see RUNBOOK)
- `SUPABASE_LOCAL_SERVICE_ROLE_KEY` GitHub Actions secret must be set for seed step to create test users
- 3 moderate vulnerabilities in `@prisma/dev` (transitive via `prisma@7.7.0`); not reachable in production; awaiting upstream fix
- 31 `no-console` warnings in server actions — accepted for server-side debug logging.
- GitHub Secrets for CI (Playwright) require one-time manual setup.
- Transitive dependency vulnerabilities in `@prisma/dev` (not reachable in production).

## Update Protocol

Expand Down
60 changes: 60 additions & 0 deletions docs/decisions/ADR-003-infrastructure-observability-hardening.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# ADR-003: Infrastructure & Observability Hardening

## Status
Accepted

## Context
As part of the modernization for Next.js 15, Sentry 10, and Prisma 7, several structural challenges were identified:
1. **PII Vulnerability**: Server-side error logs and client-side session replays were potentially capturing sensitive student data (CPF, health hashes).
2. **Type Safety Decay**: The move to Prisma 7 with the `pg` driver adapter introduced a version conflict in `@types/pg`, leading to the widespread use of `as any` in the database layer.
3. **Connection Governance**: Migrating to a driver adapter pattern (required for some Next.js environments) necessitated more explicit connection pool management to prevent exhaustion in serverless or PgBouncer environments.

## Decisions

### 1. Recursive PII Scrubbing (Sentry)
Instead of relying on basic header scrubbing, we implemented a dedicated recursive sanitization engine in `sentry.server.config.ts`. This engine traverses all event breadcrumbs and extra data, replacing values for a defined list of sensitive keys (`cpf`, `password`, `biometriaHash`, etc.) with `[SCRUBBED]`.

### 2. Dependency Pinning via Overrides
To resolve the `ClientBase` return type mismatch between `@types/pg@v8.18+` and `@prisma/adapter-pg`, we decided to:
- Pin `@types/pg` to version `8.11.11` in both `devDependencies` and the `overrides` field of `package.json`.
- This ensures that all internal and external consumers of the `pg` types are aligned with the Prisma runtime requirements, allowing for the complete removal of unsafe type assertions in `src/lib/prisma.ts`.

### 3. Connection Resilience & Heartbeat
We enhanced the `PrismaClient` initialization with:
- **Pool Governance**: Explicit `idleTimeout` and `connectionTimeout` to handle transient network issues.
- **Boot Heartbeat**: Integrated a `SELECT 1` check into the Next.js `instrumentation.ts` with a 5-second `Promise.race` timeout to verify database health during application startup, preventing "zombie" boot states.

### 4. Genkit AI Flow Contract Hardening
To prevent technical debt in AI integration, we implemented:
- **Strict Schema Enforcement**: All Genkit flows now utilize Zod schemas for input, output, and streaming, eliminating `as any` casts in the frontend.
- **Hallucination Detection**: Added Sentry monitoring to log unrecognized exercise suggestions, ensuring that AI-generated plans remain within physiological and logistical constraints defined in `src/lib/constants.ts`.

### 5. Tailwind 4 & OKLCH Unified Theme
Migrated the entire design system to Tailwind 4 (Oxide engine) to leverage:
- **Native Custom Properties**: Replaced legacy HSL `:root` variables with a unified `@theme` block.
- **OKLCH Color Space**: Adopted OKLCH tokens for consistent vibrancy and accessibility across the "Premium Dark" interface.

## Consequences

### Positive
- **Privacy Compliance**: Strict adherence to data protection standards for student information.
- **Developer Experience**: Restored full IDE intellisense and type-checking in the database and AI layers.
- **Aesthetic Excellence**: Unified, vibrant UI with optimized build performance via Tailwind 4.
- **Operational Visibility**: Sentry alerts for both infrastructure failures and AI "hallucinations".

### Negative
- **Maintenance**: We must monitor Prisma and Genkit SDK updates to revert specific type overrides or casts once upstream packages reach full alignment with Next.js 15.

---

## Visual Documentation

### 1. Premium Dark Interface (Tailwind 4)
The new design system ensures a high-fidelity, high-contrast experience using OKLCH color tokens.

![Student Dashboard - Premium Dark](file:///home/emiyakiritsugu/.gemini/antigravity/brain/f9bac6cb-9ccd-44da-af5f-669178bd052a/student_dashboard_view_1775903233752.png)

### 2. AI Workout Generator (Genkit)
Strictly typed integration between the AI service and the student portal.

![AI Workout Generator UI](file:///home/emiyakiritsugu/.gemini/antigravity/brain/f9bac6cb-9ccd-44da-af5f-669178bd052a/workout_generator_final_result_1775903924170.png)
Comment on lines +1 to +60

@coderabbitai coderabbitai Bot Apr 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Address the Prettier failure for this ADR file.

CI already reports formatting issues here; please run Prettier on this file before merge.

🧰 Tools
🪛 GitHub Actions: CI

[warning] 1-1: Prettier --check reported formatting issues in this file.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/decisions/ADR-003-infrastructure-observability-hardening.md` around
lines 1 - 60, Run Prettier on the ADR file
(ADR-003-infrastructure-observability-hardening.md) to fix CI formatting
failures; open the file (the document titled "ADR-003: Infrastructure &
Observability Hardening") and apply your project's Prettier config (e.g.,
npm/yarn run prettier --write or your editor's format command) so the markdown
spacing, headings, lists, and image links are normalized, then re-run lint/CI
and commit the reformatted file.

Comment on lines +55 to +60

@coderabbitai coderabbitai Bot Apr 11, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Replace local file:// image paths with repo-relative assets.

These links only work on one machine and will be broken in GitHub/docs rendering. Move images into the repo (e.g., docs/assets/...) and reference them relatively.

Proposed fix pattern 
-![Student Dashboard - Premium Dark](file:///home/.../student_dashboard_view_1775903233752.png)
+![Student Dashboard - Premium Dark](../assets/student_dashboard_view_1775903233752.png)

-![AI Workout Generator UI](file:///home/.../workout_generator_final_result_1775903924170.png)
+![AI Workout Generator UI](../assets/workout_generator_final_result_1775903924170.png)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
![Student Dashboard - Premium Dark](file:///home/emiyakiritsugu/.gemini/antigravity/brain/f9bac6cb-9ccd-44da-af5f-669178bd052a/student_dashboard_view_1775903233752.png)
### 2. AI Workout Generator (Genkit)
Strictly typed integration between the AI service and the student portal.
![AI Workout Generator UI](file:///home/emiyakiritsugu/.gemini/antigravity/brain/f9bac6cb-9ccd-44da-af5f-669178bd052a/workout_generator_final_result_1775903924170.png)
![Student Dashboard - Premium Dark](../assets/student_dashboard_view_1775903233752.png)
### 2. AI Workout Generator (Genkit)
Strictly typed integration between the AI service and the student portal.
![AI Workout Generator UI](../assets/workout_generator_final_result_1775903924170.png)
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/decisions/ADR-003-infrastructure-observability-hardening.md` around
lines 55 - 60, The markdown uses local file:// image URLs (e.g.,
file:///home/.../student_dashboard_view_1775903233752.png and
workout_generator_final_result_1775903924170.png) which won't render in the
repo; move those PNGs into the repository (suggested folder docs/assets/) and
update the image references in ADR-003 to use repo-relative paths (e.g.,
![Student Dashboard - Premium
Dark](./assets/student_dashboard_view_1775903233752.png) and ![AI Workout
Generator UI](./assets/workout_generator_final_result_1775903924170.png));
ensure the filenames match exactly and commit the assets alongside the updated
docs/decisions/ADR-003-infrastructure-observability-hardening.md.

Loading
Loading