REPOSITORY OVERVIEW

Live repository statistics

★ 3Stars

⑂ 0Forks

◯ 21Open issues

◉ 3Watchers

55/100

OPENREPOHUB HEALTH SIGNAL

Mixed signals

A transparent discovery signal based on current public GitHub metadata.

Recent activity35% weight

100

Community adoption25% weight

Maintenance state20% weight

License clarity10% weight

Project information10% weight

100

This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.

README preview

Co-Operability.com

My Next.js portfolio website on Vercel. Several smaller projects within.

TODO:

Quick wins / hygiene

OC input fields block numbers but should pop up numpad on mobile
SEO; site:cooperability.com
Create .editorconfig for consistency
Add .npmrc for Yarn users
commitlint for commit messages
Migrate Yarn PnP → pnpm 11 (11.13.0, not 11.1.0) — see Package Manager: Executive Recommendation. Blocking for Turbopack/App Router; do it as part of that upgrade
Purge .yarn/cache from git history with git filter-repo (separate follow-up — the migration alone won't reclaim the 508 MB .git)
somehow clean up root repo with symlinks to subdirectories
Drop the leftover ls -la && ls -la .yarn debug prefix from the build script
Fix engines.yarn: ">=1.22.0" — it contradicts the Yarn 4 PnP setup and silently allows Yarn 1 installs
Remove prop-types (redundant under TypeScript) and convert the last JS files (src/components/date.js, src/components/providers.js) to TSX
Bump tsconfig target from es5 to ES2022 (es5 forces needless downleveling on a Node 22 / modern-browser target)

AI infrastructure (the main event)

Add an /api LLM route using the Anthropic SDK (claude-opus-4-8 / claude-sonnet-5) with streaming responses, and a shared src/lib/ai/ client module
Wire Prompt Composer to a live model: preview/critique the composed prompt, score it against the research-backed rubric it already encodes, suggest missing components
Ship an eval harness (fixture prompts → expected properties, run in CI on a cheap model) so prompt/tooling changes can't silently regress
Rate-limit + abuse-guard any public AI endpoint (Vercel KV / Upstash, per-IP token bucket, max token caps, request size limits) before it costs money
Add server-side prompt-injection hygiene: never echo untrusted MDX into system prompts, pin system prompts server-side, never expose the API key to the client
RAG/chat over src/resources/** MDX + docs (embed at build time, ship a small static index — no vector DB needed at this size)
Implement the MCP server that docs/MCP.md currently only describes — expose site content/tools (opioid conversion, prompt composition) over MCP; otherwise mark the doc as aspirational
Add public/llms.txt + llms-full.txt so agents can index the site correctly
~~Add a root CLAUDE.md + repo-local skills/agents under .claude/ / .cursor/~~ (done — see CLAUDE.md, AGENTS.md)
Cost/latency observability for AI calls (token counts, p95 latency, spend per route) — log to Vercel Observability or an OTel exporter
Enable prompt caching + a cheap-model fallback path for anything user-facing
Decide and document an AI usage/privacy stance in PrivacyStatement.mdx (what's sent to model providers, retention, opt-out)

Framework & architecture modernization

Migrate Pages Router → App Router — you're on Next 16 but still entirely on src/pages; unlocks RSC, streaming, route handlers, and the Metadata API
Replace the hand-rolled <Head> in layout.tsx with the Metadata API / generateMetadata (fixes SEO, OG, and the <html lang="en"> inside <Head> bug)
Collapse the dual component tree: root components/ui + lib/ vs src/components + src/lib, with @/* → ./* resolving to root. Point components.json at src/ and delete the duplication (this is the real fix for the "symlinks" TODO)
Add _document equivalents / custom 404 + 500 pages and a top-level error boundary
Adopt next/font for self-hosted, layout-shift-free fonts
Move the inline dangerouslySetInnerHTML service-worker registration in _app.tsx into Serwist's own registration (it's a CSP unsafe-inline liability)
Upgrade Tailwind 3 → 4 (CSS-first config, faster engine); audit tailwind.config.js and tw-animate-css afterward
Reconsider next-mdx-remote vs. compile-time MDX now that RSC makes static MDX cheaper

CI/CD & quality gates

next.config.js sets eslint.ignoreDuringBuilds: true — fix the underlying lint errors and turn it back on
yarn test is jest --watch, so it's unusable in CI. Add test:ci (jest --ci --coverage) and keep test interactive
Add a real CI workflow — right now only security-audit.yml exists. Gate PRs on typecheck + lint + test + build
Test coverage is one file (src/__tests__/pages/index.test.tsx). Prioritize opioid-converter/utils/calculations.ts (clinical math — highest-consequence code in the repo), mandelbrot-explorer/utils/calculations.ts, and prompt-composer/utils/helpers.ts; set coverage thresholds
Add Playwright E2E + @axe-core/playwright for the theme-switch, PWA install, and converter flows (already listed as an accessibility maintenance task — this is the mechanism)
Add Lighthouse CI with perf/a11y budgets on PRs, replacing the manual yarn access run
Consider Vitest over Jest (faster, native ESM, less SWC/PnP config surface)
Add SECURITY.md, CODEOWNERS, a PR template, and a LICENSE (repo has issue templates but none of these)
Pin GitHub Actions to commit SHAs and set explicit least-privilege permissions: on each workflow
Make the high severity audit blocking, or document why it stays advisory

Security & runtime hardening

Add real security headers via next.config.js headers() — CSP, HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy. Today only images have a CSP
Add error tracking (Sentry or Vercel's) — currently no visibility into client-side runtime failures
Delete or repurpose the placeholder src/pages/api/hello.ts
Audit committed artifacts: accessibility-reports/, tsconfig.tsbuildinfo, .swc/ shouldn't be in git

Content & product

The README's dependency list has drifted (missing Radix, lucide, next-sitemap, serwist…). Either generate it or cut it — package.json is the source of truth
Add per-applet PWA icons + maskable variants (already noted under PWA Next Steps)
Structured data (JSON-LD Person/SoftwareApplication) for the portfolio and each demo
OG image generation via @vercel/og per page/demo
RSS/JSON feed for resources/
Add a "how it's built" case-study page — the AI infra work above is the portfolio piece

Developer Tooling

This project uses a comprehensive suite of quality control tools. For complete documentation, see docs/Tooling.md.

Quick Reference:

yarn dev - Start development server
yarn lint / yarn lint:mdx - ESLint checking (includes MDX validation)
yarn format / yarn format:mdx - Prettier formatting
yarn test - Jest + React Testing Library
yarn typecheck - TypeScript validation
yarn analyze - Webpack bundle analysis
yarn access - Accessibility audits (ESLint + Axe-core + Lighthouse)
yarn audit / yarn audit:critical - Security vulnerability scanning

Security: Pre-push hooks and GitHub Actions block vulnerable code. See docs/Tooling.md#security-auditing.

Key Technologies:

Linting: ESLint with TypeScript, Next.js, and MDX support
Formatting: Prettier with automatic MDX prose wrapping
Testing: Jest with @testing-library/react and jest-dom matchers
Automation: Husky (pre-commit + pre-push security), lint-staged, GitHub Actions
Package Management: Yarn Plug'n'Play (PnP) for zero-install, deterministic dependencies
UI Components: shadcn/ui (Tailwind + Radix UI primitives)
Bundle Analysis: Webpack Bundle Analyzer for optimization
Accessibility: Automated testing with axe-core CLI and Lighthouse
Icons: skillicons.dev (theme-aware tech stack icons via simple-icons.org)

See docs/Tooling.md for setup instructions, troubleshooting, and best practices.

Performance & Responsive Design

This project implements comprehensive performance optimizations and a content-first responsive design strategy:

Performance:

Dynamic imports with disabled SSR for heavy components (~85KB bundle reduction)
Loading skeletons to prevent CLS (Cumulative Layout Shift)
Debounced resize handling (100ms) for smooth responsiveness
Fluid spacing with CSS clamp() for breakpoint-free scaling

Responsive Design:

Primary breakpoint: 525px (useResponsive hook) for site-wide mobile/desktop splits
Tailwind-aligned breakpoints: sm (640px), md (768px), lg (1024px), xl (1280px)
Philosophy: Break where content naturally requires it, not at arbitrary device widths

See docs/Performance.md for complete optimization strategies, breakpoint implementation, and best practices.

Tech Stack Icons & SVG Configuration

This project uses skillicons.dev for theme-aware technology stack icons on the demos page. These icons automatically adapt to light/dark theme and provide consistent, professional styling.

Implementation:

Icons source from simple-icons.org via skillicons.dev API
Dynamic theme switching via next-themes integration
Fallback to custom PNGs for unavailable icons (shadcn/ui, Poetry)

Security Configuration (next.config.js):

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'skillicons.dev', pathname: '/icons/**' },
    ],
    dangerouslyAllowSVG: true,
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

Security Measures:

✅ dangerouslyAllowSVG enables external SVG loading (required for skillicons.dev)
✅ CSP blocks script execution: script-src 'none' prevents XSS attacks
✅ Sandbox environment limits SVG capabilities
✅ Trusted source only (skillicons.dev domain restriction)
✅ Follows Vercel's official security recommendations

Benefits:

Automatic light/dark theme adaptation
Consistent color grading across all tech icons
Professional, scalable vector graphics
Single source of truth for icon styling

Trade-offs:

Requires external domain allowlist for SVGs
Minor dependency on third-party service (skillicons.dev)
Some icons unavailable (resolved with custom fallbacks)

Privacy Policy, SEO, Analytics

Privacy: Privacy-forward Next Analytics is used instead of Google Analytics for better anonymization.
SEO: See docs/SEO.md

Project Dependencies

Runtime Dependencies (`dependencies`)

@heroicons/react: SVG icons as React components.
@mdx-js/loader: Webpack loader for MDX files.
@mdx-js/react: React components for rendering MDX.
@next/mdx: Integration for using MDX with Next.js.
@tailwindcss/typography: Tailwind plugin for beautiful typography defaults.
@vercel/analytics: Vercel integration for website analytics.
@vercel/speed-insights: Vercel integration for performance monitoring.
date-fns: Modern JavaScript date utility library.
gray-matter: Parses front-matter from files (e.g., Markdown metadata).
next: The React framework for production.
next-mdx-remote: Renders MDX content dynamically in Next.js.
next-themes: Theme switching support for Next.js apps.
prop-types: Runtime type checking for React props.
react: JavaScript library for building user interfaces.
react-dom: Serves as the entry point to the DOM and server renderers for React.
remark: Markdown processor.
remark-html: Plugin for remark to serialize Markdown to HTML.
sharp: High-performance Node.js image processing library.

Development Dependencies (`devDependencies`)

@eslint/compat: Compatibility utilities for ESLint flat config.
@eslint/eslintrc: Utilities for using .eslintrc configs with flat config.
@eslint/js: Core JavaScr