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
├── api-legacy-vercel-functions/AGENTS.md    # Serverless patterns
├── 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 <img> alt attribute.

Sanity Blog Publishing

Quick Publish Workflow:

# Publish single article from Sanity
npm run sanity:publish-single <article-slug>

# 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/                       # Vite app (legacy, being phased out)
│   ├── App.tsx                # React Router configuration
│   ├── pages/                 # Route components (to be migrated)
│   └── components/            # Component library
│
├── shared/                    # Symlinked shared code
│   ├── components/            # Design system (from src/components)
│   ├── hooks/                 # Custom React hooks
│   ├── styles/                # Design tokens & global styles
│   └── locales/               # i18n translation files
│
├── api-legacy-vercel-functions/  # Serverless functions
│   ├── cors.js                # CORS middleware
│   ├── openai-chat.js         # AI chat endpoint
│   ├── save-contact.js        # Contact form handler
│   └── download-cv.js         # Secure CV download
│
├── scripts/                   # Automation & tooling
│   ├── linear/                # Issue management
│   ├── sentry-mcp.js          # Observability queries
│   └── generate-*.js          # Code generation
│
├── docs/                      # Documentation
│   ├── LLM_COMPONENT_GENERATION_RULES.md (12,000+ words)
│   ├── NEXTJS_MIGRATION_PLAN.md
│   ├── LINEAR_AUTOMATION.md
│   └── *_MCP_SETUP.md         # MCP integration guides
│
└── .claude/                   # Claude Code configuration
    ├── settings.json          # Hooks (auto-format, safety)
    └── commands/              # Custom slash commands

Technology Stack

Frontend

• React 19: Concurrent features, Suspense, automatic batching
• TypeScript 6.x: Strict mode, decorators, import attributes
• Next.js 16.2.x: App Router, Server Components, Streaming SSR
• Vite 6.4: Lightning-fast HMR, optimized production builds
• React Router 7: Client-side routing with lazy loading (Vite app)

Styling & Design

• CSS Modules: Scoped styling with consistent naming conventions
• Design Tokens: CSS custom properties in src/styles/variables.css
• Progressive Enhancement: @supports queries for modern features
• Logical Properties: margin-inline, padding-block (RTL-ready)
• Responsive Design: Mobile-first with breakpoint system

State & Data

• React Hooks: useState, useEffect, useContext, custom hooks
• i18next: Internationalization with React bindings
• EmailJS: Contact form email delivery
• OpenAI API: GPT-4 chat with function calling

Backend Services

• Vercel Serverless: Node.js functions with CORS middleware
• GitHub Pages: Static site hosting with custom domain
• Sanity CMS: Headless blog content management
• Sentry: Error tracking and performance monitoring

Developer Tools

• Storybook 10: Component development and documentation
• Vitest: Unit testing with jsdom environment
• Testing Library: User-centric testing utilities
• Playwright: Visual regression testing via Storybook
• ESLint + Stylelint: Code quality enforcement
• Prettier: Consistent code formatting

AI & Automation

• MCP (Model Context Protocol): GitHub, Figma, Context7, TypeScript LSP
• Linear API: Programmatic issue management
• Sentry REST API: Observability queries and dashboards
• Claude Code: Custom commands and hooks for AI pair programming

📱 Component Features

Native Share Integration

The SocialShare component implements progressive enhancement with the Web Share API:

Native Share Support

• Detects Web Share API availability on mobile devices
• Provides seamless sharing via device native share sheet
• Falls back gracefully to clipboard copying when unavailable

Responsive Design

• Icon-only mode on mobile devices for compact display
• Full button text on desktop environments
• Proper alignment with other social media icons

Progressive Enhancement

• Feature detection for navigator.share availability
• Automatic fallback to clipboard copy functionality
• Error handling for share failures with retry mechanism

Accessibility

• ARIA labels for both native share and copy actions
• Keyboard navigation support
• Screen reader friendly with appropriate role attributes

Browser Support

• Modern mobile browsers: Native share functionality
• Desktop browsers: Clipboard copy fallback
• Legacy browsers: Standard clipboard copy behavior

The implementation follows Web Share API best practices with proper error handling and provides a consistent user experience across all device types.

⚙️ Testing & Quality

Testing Stack

npm test                         # Run all tests
npm run test:watch               # Watch mode
npm run test:coverage            # Generate coverage reports
npm run test:a11y                # Accessibility testing
npm run test:visual              # Visual regression tests
npm run test:visual:update       # Update visual baselines

Test Suite Coverage:

• Unit Tests: Component behavior, props, state management (>80% coverage requirement)
• Integration Tests: Chat workflows, email forms, navigation patterns
• Accessibility Tests: axe-core on all pages and Storybook stories
• Visual Regression: Playwright screenshots via Storybook test-runner
• Translation Coverage: Ensures all i18n keys exist in EN/FI/SV

Testing Libraries:

• Vitest + jsdom: Fast unit testing with React support
• Testing Library: User-centric component testing
• axe-core: Automated accessibility auditing
• Playwright: Visual regression and E2E capabilities

Code Quality

npm run lint                     # ESLint + Stylelint
npm run lint:fix                 # Auto-fix linting issues
npm run format                   # Prettier formatting
npm run typecheck                # TypeScript validation

Quality Standards:

• ESLint: TypeScript strict mode, React best practices, a11y rules
• Stylelint: CSS Modules standards, logical properties enforcement
• Prettier: 2-space indentation, single quotes, trailing commas
• TypeScript: No implicit any, strict null checks, unused variables blocked

Observability

Sentry Integration:

npm run sentry:issues            # Query unresolved issues
npm run sentry:releases          # List recent releases
npm run generate:sentry-summary  # Generate JSON summary

MCP Testing:

npm run github:mcp:test          # Test GitHub MCP connectivity
npm run figma:mcp:test           # Test Figma MCP connectivity
npm run ts:mcp:status            # Validate TypeScript LSP

Component Development

Storybook:

npm run storybook                # Launch Storybook dev server
npm run build-storybook          # Build static Storybook
npm run storybook:deploy         # Deploy to GitHub Pages

WIP Badge System:

• All stories display a localized "Work in Progress" badge by default
• Badge removed via parameters: { wip: { disabled: true } } after passing:
  • ✅ Accessibility tests (axe-core violations = 0)
  • ✅ Visual regression (no unexpected diffs)
  • ✅ Translation coverage (all keys in EN/FI/SV)

🌐 Internationalization

The site supports three languages with complete translation coverage:

• English (EN): Primary language with full content
• Finnish (FI): Native language support
• Swedish (SV): Regional language support

Structure:

• Translation files: nextjs-app/shared/locales/{en,fi,sv}/translation.json
• Namespace organization for maintainability
• 100% coverage requirement enforced by tests

Usage:

• Always wrap user-facing text with useTranslation() hook
• Use nested object notation like "navigation.home" for organization
• Update all three locale files simultaneously before merging

🔐 Security & Performance

Security Measures:

• Password-protected content delivery
• Environment-based configuration with .env.local (gitignored)
• CORS-enabled API endpoints with strict origin validation
• Sanitized user inputs and XSS protection
• No secrets in version control (see .gitignore)

Performance Optimizations:

• Code splitting with dynamic imports and React.lazy()
• Image optimization and lazy loading
• Service worker caching strategy (Vite app)
• Bundle analysis and tree shaking
• Compressed asset delivery with Brotli/Gzip
• Aggressive filename hashing for cache busting

🚀 Build & Deployment

Production Builds

Next.js App:

npm run build                    # Build Next.js app (production)
npm run start                    # Start Next.js production server

Vite App (legacy):

npm run build                    # Vite production build
npm run preview                  # Preview Vite production build
npm run cache-bust               # Manual cache busting

Deployment Strategy

Hybrid Deployment:

• Vercel: Hosts Next.js app + serverless API functions

  • Automatic deployments from main branch
  • Environment variables managed in Vercel dashboard
  • Edge functions for auth, API routes, webhooks

• GitHub Pages: Hosts legacy Vite app + Storybook

  • Manual deployment via npm run deploy
  • Custom domain: digitaltableteur.com
  • Aggressive cache busting with hashed filenames

Deployment Commands:

npm run deploy                   # Deploy Vite app to GitHub Pages
npm run deploy-with-storybook    # Deploy with visual diff report
npm run storybook:deploy         # Deploy Storybook standalone
npm run generate:sitemap         # Generate sitemap.xml

Cache Strategy

Vite Build:

• Automatic filename hashing for JS/CSS assets
• Manual cache-bust script adds version metadata
• .nojekyll file prevents GitHub Pages Jekyll processing

Next.js Build:

• Built-in asset hashing and optimization
• Cache-Control headers configured via next.config.ts
• Vercel CDN handles cache invalidation

Environment Variables

Production (Vercel):

• All secrets stored in Vercel project settings
• Separate preview/production environments
• Automatic NEXTPUBLIC prefix for client-side vars

Production (GitHub Pages):

• Public environment variables in GitHub Secrets
• Deploy workflow injects variables at build time
• No server-side secrets (static hosting only)

🚀 CI/CD Pipeline

GitHub Actions:

• Automated Testing: ESLint, Stylelint, and Vitest on every PR
• Preview Deployments: Automatic staging environments for pull requests
• Production Deployment: Automated builds and cache busting

Branch Protection:

• Required status checks for code quality
• 1 approval required for main branch
• Squash commits on merge
• Delete branch after merge

🤝 Contributing

Development Guidelines

• TypeScript: Use strict typing for all new components and functions
• CSS Modules: Follow existing pattern with design tokens (never inline styles)
• Internationalization: Add translations for all user-facing text (EN/FI/SV)
• Component Creation: Always read docs/LLM_COMPONENT_GENERATION_RULES.md first
• Storybook: Include .stories.tsx for every component
• Testing: Maintain >80% test coverage, include accessibility tests
• Documentation: Update CLAUDE.md, AGENTS.md, README.md, and copilot-instructions.md together

Workflow

1. Fork the repository
2. Create Branch: Follow naming convention from docs/BRANCH_NAMING.md

   git checkout -b DT-XXX-feat-description
   

3. Develop: Make changes following conventions above
4. Quality Checks:

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

5. Commit: Use Conventional Commits format

   git commit -m "feat: add amazing feature"
   

6. Push: Push to your branch

   git push origin DT-XXX-feat-description
   

7. Pull Request: Open PR with detailed description
8. Review: Address feedback and ensure CI passes
9. Merge: Squash commits on merge, delete branch after

Pre-commit Checklist

Before creating a PR: