Digitaltableteur

 _____   _______

| \ | | | | | | | | | | | | | | | || | | | |_____/ |_|

Digitaltableteur

"Iteration beats perfection—ship today, learn tomorrow, refine forever."

Digitaltableteur is a hybrid monorepo portfolio website featuring both Next.js 16 (production) and Vite (legacy) applications. Built with React 19 and TypeScript 6.x, it showcases a comprehensive design system, multi-language support (EN/FI/SV), AI-powered chat interface, and enterprise-grade tooling including Sentry observability, Linear issue management, and MCP (Model Context Protocol) integrations.

🚀 Features

Core Architecture

• Hybrid Monorepo: Next.js 16 App Router (production) + Vite 6.4 (legacy) in parallel migration
• AI Documentation System: Hierarchical CLAUDE.md/AGENTS.md structure optimized for AI assistants
• Design System: 50+ components with CSS Modules, design tokens, Storybook, and visual regression testing
• Type Safety: TypeScript 6.x strict mode with comprehensive interfaces and JSDoc documentation

User Experience

• Multi-language Support: Complete i18n with English, Finnish, and Swedish (100% translation coverage)
• AI Chat Interface: OpenAI-powered chat with guided email workflow, dynamic component injection, markdown rendering
• Responsive Design: Mobile-first with progressive enhancement (backdrop-filter, gap, :has() selector)
• Progressive Web App: Service worker caching, offline support, native share API integration
• Accessibility: WCAG AA compliant with axe-core testing, semantic HTML, ARIA attributes, keyboard navigation

Content & Media

• Blog Platform: Sanity CMS integration with MDX, syntax highlighting, reading time estimates
• Secure CV Download: Password-protected with API validation and rate limiting
• Image Optimization: Next.js Image component, lazy loading, responsive srcset generation
• Contact Integration: EmailJS with guided multi-step workflow, validation, and accessibility

Developer Experience

• Storybook 10: Component development with WIP badge system, visual regression testing
• Testing: Vitest + Testing Library (>80% coverage target), accessibility tests, E2E with Playwright
• MCP Integrations: GitHub, Figma, Context7, TypeScript LSP, Sentry for AI-assisted development
• Linear Automation: Programmatic issue creation/update, label management, state workflows
• Sentry Observability: Error tracking, performance monitoring, release health, MCP query interface

Performance & SEO

• Code Splitting: Dynamic imports with React.lazy() (Vite) and next/dynamic (Next.js)
• Bundle Optimization: Tree shaking, minification, aggressive cache busting with content hashes
• SEO: Dynamic metadata with generateMetadata(), sitemap.xml, robots.txt, structured data
• Analytics: Google Analytics 4 integration with privacy controls

🏁 Getting Started

Prerequisites

• Node.js 18+ (LTS recommended)
• npm 9+ or compatible package manager

Installation

# Clone repository

git clone https://github.com/PetriLahdelma/digitaltableteur.git cd digitaltableteur

Install dependencies

npm install

Copy environment template

cp .env.example .env.local

Environment Configuration

Required for development:

# Analytics

VITE_GA_ID=G-XXXXXXXXXX # Google Analytics 4

Email Services

VITE_EMAILJS_SERVICE_ID=service_xxx VITE_EMAILJS_TEMPLATE_ID=template_xxx VITE_EMAILJS_PUBLIC_KEY=xxx

MCP Servers (optional for enhanced AI features)

FIGMA_TOKEN=figd_xxx # Figma design access GITHUB_MCP_PAT=github_pat_xxx # GitHub operations CONTEXT7_API_KEY=xxx # Context7 documentation access

Linear Issue Management (optional)

LINEAR_API_KEY=lin_api_xxx LINEAR_TEAM_ID=xxx LINEAR_PROJECT_ID=xxx

Akaunting Accounting (optional, self-hosted)

AKAUNTING_API_USERNAME=admin@digitaltableteur.com AKAUNTING_API_PASSWORD=xxx AKAUNTING_COMPANY_ID=1

Production only:

CV_PASSWORD=xxx                              # Secure resume download

OPENAI_API_KEY=sk-xxx # AI chat functionality SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx SENTRY_AUTH_TOKEN=xxx # Source map upload

See .env.example for complete list with descriptions.

⚒️ Development

Development Servers

# Next.js dev server (production app)

npm run dev # http://localhost:3001

Storybook component development

npm run storybook # http://localhost:6010

Code Quality & Testing

# Type checking

npm run typecheck # TypeScript validation across project

Linting

npm run lint # ESLint + Stylelint npm run lint:fix # Auto-fix linting issues

Testing

npm test # Run all tests (Vitest) npm run test:watch # Watch mode npm run test:coverage # Coverage report (>80% target) npm run test:a11y # Accessibility tests (axe-core) npm run test:visual # Visual regression (Playwright + Storybook)

Pre-commit validation (run before PR)

npm run typecheck && npm run lint && npm test && npm run build

MCP & Automation

# GitHub MCP Server

npm run github:mcp:test # Test connectivity and authentication

Figma MCP Server

npm run figma:mcp:test # Test connectivity and authentication

Context7 MCP Server

npm run context7:mcp # Launch locally (respects CONTEXT7_API_KEY) npm run context7:mcp -- --remote-check # Test remote endpoint

TypeScript LSP Status

npm run ts:mcp:status # Validate TypeScript language server npm run ts:mcp:status:stub # Generate stub status

Linear Issue Management

npx tsx scripts/linear/create-issue.ts # Interactive issue creation npx tsx scripts/linear/update-issue.ts --issue DIG-16 --state "Done" npx tsx scripts/linear/check-issue.ts DIG-16 # Display issue details

Sentry Observability

node scripts/sentry-mcp.js issues digitaltableteur 10 --unresolved npm run generate-sentry-summary # Generate dashboard data

🏗 Build & Deployment

Build Commands

# Next.js production build

npm run build # Output: .next/

Storybook static build

npm run build-storybook # Output: storybook-static/

Deployment

# Vite to GitHub Pages

npm run deploy # Build + gh-pages deployment

Vite + Storybook visual diffs

npm run deploy-with-storybook # Deploy with visual regression report

Manual cache busting

npm run cache-bust # Add version metadata + .nojekyll

Vercel (production - automatic on push to main)

vercel --prod

Hybrid Deployment Strategy:

• Vite App: GitHub Pages (https://digitaltableteur.com)
• Next.js App: Vercel (https://nextjs-app.vercel.app)
• Serverless Functions: Vercel (/api/* routes)
• Routing: Vercel rewrites route specific paths to Next.js (see vercel.json)

Build Optimizations

Vite Build:

• Tree-shaken JavaScript bundles with content hashes
• Minified CSS with vendor prefixes and logical properties
• Compressed images and fonts
• Service worker for offline caching (Workbox)
• Aggressive cache busting with filename hashing

Next.js Build:

• Server-side rendering (SSR) for SEO
• Static generation for blog posts
• Image optimization with Next.js Image component
• API routes as Vercel serverless functions
• Automatic code splitting per route

🤖 AI Documentation System

Hierarchical Structure

The project uses a hierarchical CLAUDE.md/AGENTS.md system optimized for AI assistants:

Root Documentation (Universal Rules)

├── CLAUDE.md (380 lines) # Comprehensive authority for Claude Code ├── AGENTS.md (150 lines) # Quick reference for generic agents └── .github/copilot-instructions.md # GitHub Copilot specific

Subdirectory Documentation (Specific Context) ├── app/CLAUDE.md + AGENTS.md # Next.js App Router patterns ├── shared/components/CLAUDE.md + AGENTS.md # Component library rules ├── docs/AGENTS.md # Documentation navigation └── scripts/AGENTS.md # Automation patterns

Claude Code Configuration ├── .claude/settings.json # Hooks (auto-format, safety checks) └── .claude/commands/ # Custom slash commands ├── review.md # Comprehensive code review ├── fix-issue.md # GitHub issue workflow ├── create-component.md # Component generation └── create-linear-issue.md # Issue creation

Key Features

CLAUDE.md (Claude Code Authority)

• 200-400 lines per file
• Treated as immutable system rules
• Read hierarchically (up from CWD + discovers subdirectories)
• Comprehensive patterns with file examples

AGENTS.md (Generic AI Quick Reference)

• 100-200 lines per file
• JIT (Just-In-Time) indexing with search commands
• Minimal duplication, maximum efficiency
• Copy-paste ready commands

Claude Code Enhancements

• Hooks: Auto-format (Prettier), dangerous command blocking
• Custom Commands: /review, /fix-issue, /create-component, /create-linear-issue
• Token Efficiency: 60-80% reduction per query vs monolithic docs

Usage

Claude Code (automatic):

/review                         # Comprehensive code review

/fix-issue 123 # Analyze and fix GitHub issue /create-component Button # Generate component (5 files) /create-linear-issue Implement X # Create Linear issue

Generic AI Agents (manual reference):

cat AGENTS.md                           # Root rules

cat app/AGENTS.md # Next.js patterns cat shared/components/AGENTS.md # Component rules

Documentation:

• Migration Guide
• System Summary
• Visual Tree

🎨 Design Asset Management

Fetch Figma design

If you need the raw design data, you can download the Figma file as JSON. Set the FIGMA_TOKEN environment variable with your personal access token, then run:

npm run fetch-figma

Synchronizes design tokens and assets from Figma using the API. The file is saved as figma.json in the project root.

SEO & Content Generation

npm run generate:sitemap    # Generate XML sitemap

npm run generate:llms # Create LLM-friendly content index npm run generate:alt-text # Generate accessibility descriptions (requires OPENAI_API_KEY)

generate:alt-text streams local image bytes to the OpenAI Vision API so it can describe the actual artwork; add OPENAI_API_KEY (and optionally OPENAI_ALT_MODEL) to .env.local before running, or append --force to regenerate every alt attribute.

Sanity Blog Publishing

Quick Publish Workflow:

# Publish single article from Sanity

npm run sanity:publish-single

Publish all articles

npm run sanity:publish

• See docs/SANITY_PUBLISHING_AUTOMATION.md for the complete automated publishing workflow
• See docs/SANITY_MIGRATION.md for the full migration workflow (React → Sanity via sanity:parse-posts / sanity:convert / sanity:upload, Sanity → MDX via sanity:sync-from-remote, redirects generation, cleanup helpers)

🏗 Architecture

Hybrid Monorepo Structure

digitaltableteur/

├── app/ # Next.js 16 App Router (production) │ ├── layout.tsx # Root layout with providers │ ├── page.tsx # Home page (server component) │ ├── about/page.tsx # Route pages │ ├── blog/[slug]/page.tsx # Dynamic routes │ └── api/*/route.ts # API routes (Vercel functions) │ ├── src/