# Codebase Concerns

**Analysis Date:** 2026-04-18

## Tech Debt

**Oversized mixed-responsibility modules:**
- Issue: Data access, cache policy, retry logic, query construction, and response shaping are combined in single files instead of being split into smaller modules.
- Files: `src/hooks/useProjects.ts`, `src/hooks/useHome.ts`, `src/app/[locale]/projects/ProjectsResultsClient.tsx`, `src/components/project/TagFilterPanel.tsx`, `src/components/signals/SignalFeedClient.tsx`, `src/app/[locale]/layout.tsx`
- Impact: Safe changes require understanding many unrelated branches at once; regressions are likely because query behavior, cache behavior, and UI state are tightly coupled.
- Fix approach: Split server-side data access from presentation and client state; isolate URL/query builders, Prisma queries, cache wrappers, and presentational subcomponents into separate files before adding more behavior.

**Misleading server utilities under `hooks/`:**
- Issue: `src/hooks/useProjects.ts` and `src/hooks/useHome.ts` are not React hooks. They contain Prisma queries, `unstable_cache`, retry logic, and server-only behavior.
- Files: `src/hooks/useProjects.ts`, `src/hooks/useHome.ts`
- Impact: The naming invites accidental client imports and makes server/client boundaries harder to reason about during refactors.
- Fix approach: Move these modules to a server-oriented location such as `src/lib/` or `src/server/`, then keep React hooks in `src/hooks/` only.

**Schema-drift tolerance around signal hotness columns:**
- Issue: The application carries compatibility code for `hotScore` and `isHot` column absence even though the Prisma schema declares both fields.
- Files: `src/lib/signal-hotness.ts`, `src/app/api/signals/route.ts`, `src/app/api/webhook/signals/route.ts`, `prisma/schema.prisma`, `prisma/migrations/20260224120000_add_signal_hot_fields/migration.sql`
- Impact: Deployments can run with partially applied migrations without failing fast. That reduces blast radius in production but also hides schema drift and makes behavior environment-dependent.
- Fix approach: Treat missing columns as deployment errors after rollout is stable, or move the compatibility branch behind an explicit feature flag with clear removal criteria.

**Boot-time failure for AI search route configuration:**
- Issue: The AI search route reads `process.env.N8N_AI_SEARCH_WEBHOOK!` at module scope and throws immediately if the variable is missing.
- Files: `src/app/api/search/ai/route.ts`
- Impact: A missing env var breaks route initialization instead of returning a controlled runtime error. This is fragile in local setup, preview deployments, and tests.
- Fix approach: Read the env var inside the request handler, return a structured `500`, and cover the missing-env path with tests.

## Known Bugs

**Related projects are not selected from the actual related set:**
- Symptoms: The project detail page fetches only the latest three projects and then filters that tiny set for shared tags.
- Files: `src/app/[locale]/projects/[id]/page.tsx`, `src/hooks/useProjects.ts`
- Trigger: Open a project whose related items are not in the newest three active projects.
- Workaround: None in code. The page simply renders fewer or zero related projects.

**Interactive navigation and CTA elements are placeholders:**
- Symptoms: Several visible controls navigate to `#`, the mobile menu button has no behavior, and the newsletter form has no action handler.
- Files: `src/app/[locale]/layout.tsx`, `src/components/project/ProjectCard.tsx`
- Trigger: Click `submitProject`, footer/legal/social links, the mobile menu button, or submit the newsletter form.
- Workaround: None in code. Users stay on the same page or submit a form with no integration.

## Security Considerations

**Admin and ingestion endpoints rely on a single shared API key in request bodies:**
- Risk: The code checks only `apiKey` equality. There is no request signature, timestamp, nonce, replay protection, or rate limiting in application code.
- Files: `src/lib/auth.ts`, `src/app/api/webhook/signals/route.ts`, `src/app/api/tags/maintenance/route.ts`, `src/app/api/tags/reset-projects/route.ts`
- Current mitigation: Timing-safe comparison via `crypto.timingSafeEqual` in `src/lib/auth.ts`
- Recommendations: Prefer HMAC-signed requests or provider-native webhook signatures, reject stale timestamps, add rate limiting, and keep network allowlisting outside the app if that is part of deployment.

**AI search leaks query text through URL-based webhook forwarding:**
- Risk: The route forwards user search text and filters to an external service with a `GET` request query string.
- Files: `src/app/api/search/ai/route.ts`
- Current mitigation: Not detected in code.
- Recommendations: Send the payload with `POST`, avoid placing search text in URLs, and document the data handling expectations for the external n8n workflow.

**Raw project markdown can load third-party images:**
- Risk: Markdown rendering sanitizes HTML, but image URLs still render through plain `<img>` elements. If project content is not fully trusted, remote images can leak user IPs and referrers to arbitrary hosts.
- Files: `src/components/project/MarkdownContent.tsx`
- Current mitigation: `rehype-sanitize` removes unsafe HTML, and external links use `rel="noopener noreferrer"`.
- Recommendations: Proxy images, restrict allowed image hosts, or disable markdown images for untrusted content. This concern depends on whether project content is curated or user-submitted; the code alone does not establish that trust boundary.

## Performance Bottlenecks

**Signal ingestion performs per-item existence checks and upserts sequentially:**
- Problem: Each signal performs validation, `findUnique`, and `upsert` inside a loop. The route processes up to 100 signals per request and does not batch database writes.
- Files: `src/app/api/webhook/signals/route.ts`
- Cause: The ingestion path is written for straightforward correctness and partial failure reporting, not throughput.
- Improvement path: Preload existing records in bulk, batch inserts/updates where possible, and use a transaction or job queue if partial writes are unacceptable.

**Project and signal text search use `contains` scans without matching full-text indexes:**
- Problem: Search endpoints query multiple text fields with case-insensitive `contains`, but the Prisma schema indexes only sorting/filter columns such as `slug`, `status`, `createdAt`, `githubStars`, `publishedAt`, `hotScore`, and `engagement`.
- Files: `src/hooks/useProjects.ts`, `src/app/api/signals/route.ts`, `prisma/schema.prisma`
- Cause: Search logic is application-level string matching with no dedicated full-text search index.
- Improvement path: Add PostgreSQL full-text search or trigram indexes for project and signal search fields, or move search to a dedicated search service.

**Silent fallback paths can cache outage-shaped responses:**
- Problem: Several server-side queries catch database errors and return empty arrays or zero counts instead of surfacing failure.
- Files: `src/hooks/useProjects.ts`, `src/hooks/useHome.ts`
- Cause: The code prefers graceful degradation, combined with `unstable_cache` wrappers in the same modules.
- Improvement path: Separate fallback behavior from cached fetchers, emit structured telemetry, and avoid caching degraded empty results for homepage and listing data.

**AI search hydrates external results with local DB lookups and in-memory reordering:**
- Problem: The AI route requests candidate IDs from n8n, fetches projects from the database, then matches records back to the remote order with repeated `find` calls.
- Files: `src/app/api/search/ai/route.ts`, `src/hooks/useProjects.ts`
- Cause: Remote ranking and local hydration are stitched together in the route layer instead of a dedicated search service.
- Improvement path: Preserve order with an ID-to-project map, keep pagination logic on one side, and avoid fetching more rows than the final page requires.

## Fragile Areas

**Projects results UI has duplicated URL, pagination, and fetch state machines:**
- Files: `src/app/[locale]/projects/ProjectsResultsClient.tsx`, `src/app/api/projects/route.ts`, `src/app/api/search/ai/route.ts`
- Why fragile: Traditional search and AI search maintain separate state, pagination, URL sync, and fetch flows inside one client component. The file also manually uses `window.history.replaceState`, which is easy to desynchronize from server-rendered state.
- Safe modification: Change one mode at a time, verify deep-linking and pagination after every edit, and extract shared query/pagination logic before adding more filters or sorts.
- Test coverage: No tests detected for `src/app/[locale]/projects/ProjectsResultsClient.tsx`, `src/app/api/projects/route.ts`, or `src/app/api/search/ai/route.ts`

**Tag maintenance endpoints mix validation, mutation, and cache invalidation in request handlers:**
- Files: `src/app/api/tags/maintenance/route.ts`, `src/app/api/tags/maintenance/service.ts`, `src/app/api/tags/reset-projects/route.ts`
- Why fragile: Business rules, Prisma writes, per-project iteration, and `revalidatePath` calls are tightly coupled. Bulk operations can change many rows and many pages in one request.
- Safe modification: Keep schema validation and mutation rules under tests, preserve transaction boundaries, and review all `revalidatePath` targets before changing route semantics.
- Test coverage: Route and service tests exist for these files, but there are no broader integration tests across Prisma, cache invalidation, and localized page rendering.

**Shared layout contains production UI plus unfinished placeholders:**
- Files: `src/app/[locale]/layout.tsx`
- Why fragile: The same layout file owns metadata, locale setup, navigation, announcement bar, newsletter section, footer, and placeholder interactions.
- Safe modification: Extract navigation, newsletter, and footer into dedicated components before wiring real integrations.
- Test coverage: No tests detected for this file.

## Scaling Limits

**Offset pagination on projects will degrade as data grows:**
- Current capacity: `src/hooks/useProjects.ts` uses `skip` and `take`; `src/app/api/projects/route.ts` allows `limit` up to `100`.
- Limit: High page numbers require larger offset scans in PostgreSQL, especially when combined with multi-join tag filters and text search.
- Scaling path: Move to cursor-based pagination for project listings or restrict deep paging with indexed sort keys.

**Signal search and sort scale with table growth, not just page size:**
- Current capacity: `src/app/api/signals/route.ts` limits pages to `50` items, but search still scans multiple text columns and sort-by-hot depends on computed/indexed metadata.
- Limit: Query latency rises as the `signals` table grows because there is no text-search index for `q`.
- Scaling path: Add dedicated search indexes and keep cursor pagination tied to indexed sort orders only.

**Bulk tag reset revalidates pages per updated project:**
- Current capacity: `src/app/api/tags/reset-projects/route.ts` accepts up to `100` projects and revalidates both locale list pages plus two detail pages per updated slug.
- Limit: A large batch creates many cache invalidations and can amplify request time.
- Scaling path: Batch revalidation, use broader tag-based invalidation if available, or move bulk operations to a background job.

## Dependencies at Risk

**`next/cache` `unstable_cache` behavior is runtime-sensitive:**
- Risk: Both server data modules include custom fallback logic for missing incremental cache support, which means cache behavior is not consistent across every execution context.
- Impact: The same function can behave differently in local development, tests, and production-like runtimes.
- Migration plan: Centralize cache wrappers in one server utility, document expected runtimes, and replace `unstable_cache` usage with stable APIs when the project upgrades to a supported alternative.

**External AI search depends on an n8n webhook contract with no local fallback:**
- Risk: The project assumes an external response shape and throws or fails requests when the webhook is unavailable or changes shape.
- Impact: `/api/search/ai` becomes a single external point of failure for AI search.
- Migration plan: Version the webhook contract, add contract tests, and consider a local adapter layer that can degrade more predictably.

## Missing Critical Features

**End-to-end test harness is absent from the repository:**
- Problem: `package.json` exposes only `pnpm test` for Vitest. No `playwright.config.*`, no `e2e/` directory, and no `test:e2e` script are present in the repository.
- Blocks: Critical user flows such as localized routing, project filtering, AI search, signals pagination, and webhook-backed content updates have no browser-level regression protection.

**User-facing submission and newsletter flows are not implemented:**
- Problem: The visible submission CTA and newsletter UI are placeholders with no connected backend or external provider.
- Blocks: Users cannot actually submit projects, subscribe to updates, or access legal/resource destinations from the shipped UI.

## Test Coverage Gaps

**Search and listing APIs are untested:**
- What's not tested: `GET /api/projects`, `GET /api/projects/[slug]`, `POST /api/search/ai`, and `GET /api/signals`
- Files: `src/app/api/projects/route.ts`, `src/app/api/projects/[slug]/route.ts`, `src/app/api/search/ai/route.ts`, `src/app/api/signals/route.ts`
- Risk: Pagination, filtering, sort correctness, env-missing behavior, and external-service failure handling can break unnoticed.
- Priority: High

**Signal ingestion path is untested:**
- What's not tested: Validation, per-item failure accounting, schema-drift fallback, and write behavior in `POST /api/webhook/signals`
- Files: `src/app/api/webhook/signals/route.ts`, `src/lib/signal-hotness.ts`
- Risk: Ingestion regressions can silently drop, mis-rank, or partially write signals.
- Priority: High

**Large client components and shared layout have no regression tests:**
- What's not tested: Filter toggling, URL synchronization, pagination controls, AI/traditional mode switching, signal feed interactions, and layout placeholders
- Files: `src/app/[locale]/projects/ProjectsResultsClient.tsx`, `src/components/project/TagFilterPanel.tsx`, `src/components/signals/SignalFeedClient.tsx`, `src/app/[locale]/layout.tsx`
- Risk: UI regressions are likely because these files are state-heavy and have many interaction branches.
- Priority: High

**Current tests focus narrowly on tag maintenance and schema validation:**
- What's not tested: Most database-backed pages and non-tag APIs outside a few route/service units
- Files: `src/app/api/tags/maintenance/route.test.ts`, `src/app/api/tags/maintenance/service.test.ts`, `src/app/api/tags/reset-projects/route.test.ts`, `src/app/api/tags/route.test.ts`, `src/lib/auth.test.ts`, `src/lib/validations.test.ts`, `src/lib/validations.tag-maintenance.test.ts`
- Risk: The test suite gives confidence for tag admin flows but not for the main product surfaces.
- Priority: Medium

---

*Concerns audit: 2026-04-18*