_____ _______
| __ \ |__ __|
| | | | | |
| | | | | |
| |__| | | |
|_____/ |_|
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