Portfolio: Cyberpunk

An interactive, multilingual developer portfolio built with Next.js 16, React 19, custom Canvas waves, and a futuristic-user-interface diagnostic-terminal aesthetic.

LIVE SITE · PRIVATE REPOSITORY

Overview

• Role: Creator, solo full-stack and creative engineer.
• Purpose: Present work, experience, and technical judgment through an editorial experience that is also a working product.
• Audience: Recruiters, engineering leaders, prospective clients, and developers evaluating design as well as implementation.
• Stack: Next.js 16 App Router, React 19, TypeScript, Tailwind CSS 4, MDX, next-intl, Framer Motion, custom Canvas waves with Perlin-style distortion, Three.js, React Three Fiber, provider-neutral AI integration, MCP/OAuth, Node.js 24 LTS, and Vercel.
• Content: Typed portfolio data and localized MDX documents support nine locales with an English fallback when a project translation is absent.
• Deployment: Vercel hosts the production application, with runtime credentials kept outside public content.
• Key Result: A living portfolio that documents the same production product visitors can explore.
• Summary: The project combines a clear technical case-study surface with a digital-glitch FUI terminal identity, interactive 3D and Canvas details, optional browser voice or dubbing feedback, localized content, and practical agent integrations.

The Problem

• Challenge: Typical portfolios describe capability but rarely demonstrate interaction design, full-stack integration, or careful product boundaries. This site had to make those abilities visible without turning the experience into decoration alone.
• Audience: Recruiters, engineering managers, prospective clients, and developers who need an understandable overview as well as credible implementation detail.
• Constraints: Expressive visuals must remain responsive and respect reduced motion. Nine locale variants must stay maintainable. Streaming AI, OAuth-protected agent access, contact and media integrations need explicit security boundaries, while the content and components must remain practical to evolve.
• Creative craft must support clarity, so terminal texture and status readouts cannot hide core navigation or project information.
• Mobile, touch, and reduced-motion paths need useful fallbacks rather than a diminished version of the portfolio.
• Private configuration and server credentials must remain outside client content while the public documentation remains helpful.
• The case study needs to evolve with the product without making every narrative change an interface-code change.

Approach & Decisions

• Architecture: Next.js App Router provides localized server-rendered structure and route handlers. Interactive shells stay on the client, while MDX, translation messages, portfolio data, and service concerns keep ownership boundaries explicit.
• Key Decisions:
  • Nine-locale content: next-intl owns locale-aware routing and messages, while each project has localized MDX with English as the documented fallback.
  • Canvas and 3D interaction: Custom Canvas waves with Perlin-style distortion, Framer Motion, and a focused Three.js/React Three Fiber hero add expressive motion without making the entire product a 3D scene.
  • FUI and diagnostic-terminal treatment: CRT texture, scanlines, glitch typography, and status language establish the futuristic interface identity while preserving readable hierarchy.
  • Optional browser voice and dubbing: useChatbotAudio, DubPopup, and user settings provide local voice or dubbing feedback and audio sequencing only when a browser supports it.
  • Overlay and stacking coordination: Boot screen, navigation, custom cursor, scanlines, chat and dubbing popups, and the 3D hero use deliberate stacking rules instead of a fragile fixed layer count.
  • Oz assistant design: /api/chat streams through multi-provider AI model routing with primary and fallback providers, grounded in static portfolio data and deeper MDX context, with explicit UI tools for useful actions.
  • Client, server, and state boundaries: Providers handle theme, internationalization, and music. Chat preferences remain local browser state, and the custom filter store stays narrowly scoped.
  • MCP and OAuth: Read-only portfolio tools use OAuth 2.1 Authorization Code flow, PKCE S256, and the portfolio.read scope instead of exposing broad account access.
• Trade-offs: The experience favors purposeful Canvas and selectively loaded 3D details over a heavier all-3D presentation. Browser voice and dubbing are optional feedback rather than a server-side speech pipeline.
• Data Flow: Visitor input reaches /api/chat, which applies neutral primary-and-fallback service routing with relevant portfolio data or MDX context. A streamed response can return text and UI actions to the chatbot; supported browsers may optionally use local voice or dubbing feedback.
• App Router structure: Localized pages, project documents, discovery routes, and route handlers stay in one application without forcing browser-only widgets into server work.
• Content ownership: Typed data provides concise portfolio facts, while MDX carries longer editorial project narratives and shared MDX components preserve presentation conventions.
• Client interaction shells: Browser capabilities are isolated in client components and providers so server-rendered content can remain direct and dependable.
• Visual language: CSS tokens coordinate the FUI palette, CRT texture, scanlines, and glitch treatment instead of scattering one-off visual values.
• Server boundary: Route handlers own credentials and integrations, so public documents describe capabilities without exposing private configuration.

Key Results & Impact

• Outcome: The finished portfolio gives visitors both a fast orientation layer and a deeper account of the systems behind it.
• Quality and validation: ESLint, TypeScript checking, and production builds provide repeatable readiness checks instead of unverified performance claims.
• Security controls: Chat abuse boundaries use signed temporary lockdown and rate-oriented protections, while MCP authorization uses narrow read-only scopes and one-time authorization-code handling.
• Comparison and evolution: The product advances the earlier Portfolio: Glass into a richer, modular portfolio that can carry localized editorial detail and agent-facing capabilities.
• Impact: It demonstrates creative frontend work alongside maintainable content, integration, security, and deployment decisions.
• Discoverability: Human-readable and machine-readable routes make the public project understandable to visitors and compatible read-only tools.
• Responsive confidence: The design keeps navigation, content density, and controls usable across pointer, touch, and reduced-motion contexts.

Technical Deep Dive

• Notable Details: The design system combines CRT-like texture, glitch typography, Canvas wave interaction, a focused 3D hero, music controls, and locale-aware content without tying every system to one client state container.
• Verification: Linting, type checking, and production builds are run as quality gates. Responsive layouts and reduced-motion or coarse-pointer branches are reviewed as part of UI changes.
• Optimizations: Client-only interactive shells isolate browser features. The project keeps content in MDX and data modules, uses modular components, and avoids claiming universal measured outcomes that are not continuously audited.
• Code Quality: TypeScript types, organized route handlers, focused providers, narrow stores, and service or security modules make ownership easier to understand and change.
• Links and References: See components/sections, components/ui, components/chatbot, components/providers, content/projects, messages, data, lib/mcp, lib/security, lib/services, and stores.
• Supporting systems: SEO and discovery include PWA metadata, robots, sitemap, JSON-LD, humans and LLM-readable documents. Vercel Analytics and Speed Insights support observation, with an analytics opt-out.
• Chat boundary: /api/chat validates same-origin requests. A separate signed temporary lockdown cookie carries an abuse restriction when controls are activated, rather than signing the request itself.
• Assistant context: Neutral service routing uses typed portfolio facts and relevant MDX context, then can return approved navigation, filtering, enabled project-gallery access, contact, music, theme, or language actions. Gallery access is feature-gated and not presented as a universal mobile action.
• Browser audio: Optional dubbing and voice feedback follow user settings and browser support, keeping audio sequencing in the client experience.
• Contact and media: /api/contact validates and rate-limits SMTP submissions. Spotify uses /api/spotify/login, /api/spotify/callback, and /api/spotify/now-playing rather than a generic music route.
• Project gallery: /api/gallery/[slug] is a rate-limited project-media surface used for supported project galleries.
• MCP transport: Streamable HTTP, legacy SSE and message compatibility endpoints, plus health checks, support the read-only portfolio surface.
• Authorization: OAuth 2.1 Authorization Code with PKCE S256 and portfolio.read protects MCP clients. Production uses atomic one-time code redemption through Upstash Redis with a local fallback.
• Rendering boundary: Server components prepare documents and metadata; client components add interactive shells, without claiming that every route uses one rendering mode.
• Accessibility behavior: Semantic structure, labeled navigation and controls, reduced Canvas and glitch motion, and a coarse-pointer cursor rule keep effects subordinate to use.
• Operational routes: Localized middleware and fallback maintain content parity. Metadata, manifest, robots, sitemap, JSON-LD, llms.txt, llms-full.txt, humans.txt, well-known documents, and OpenAPI support discovery.
• Resilience: Visual and audio enhancements degrade gracefully, while responsive layouts adapt hierarchy, spacing, and controls before removing meaningful content.
• Private data boundary: Static public facts and MDX can be rendered openly; secrets and integration configuration remain in server environment variables.
• Runtime quality: Node.js 24 LTS is the intended runtime, and lint, type checking, and production builds remain the repeatable quality gates.
• Internationalization: Route-aware messages and localized MDX keep labels, metadata, and project narratives aligned across all supported languages.
• Content fallback: If a project translation is unavailable, the loader can render the English project document instead of presenting an empty detail page.
• Discovery surface: Machine-readable documents complement the human case study, making portfolio facts available to compatible tools without granting write access.
• Deployment boundary: Vercel Fluid Compute hosts the application with Node.js 24 LTS, while external credentials remain environment configuration rather than content.

Reflections

• What Worked: The strongest result is a unified portfolio where interface, localized narrative, AI assistance, music, and discovery surfaces feel like one product.
• What I Would Improve: Continue simplifying the most demanding visual paths as browser and device behavior changes, while preserving the editorial personality of the product.
• Lessons Learned: Streaming AI and rich interaction are easier to maintain when server integrations, browser-only behavior, and localized content have clear boundaries.
• High-intensity visual systems need enough quiet space for editorial content to remain the primary reading task.
• Clear boundaries between static data, MDX, browser state, and server services lower the cost of future changes.
• Results should describe repeatable practices and evidence, not context-free performance figures.

My Contributions

• Frontend and design architecture: Designed the visual system, responsive page sections, HUD-like composition, Canvas waves, 3D hero integration, custom cursor behavior, and content presentation.
• AI and Oz integration: Built the streaming assistant surface, provider fallback approach, portfolio and MDX context use, UI actions, local session choices, and optional browser voice feedback.
• Browser voice and dubbing: Connected user-controlled browser audio settings, dubbing presentation, and client-side sequencing without presenting it as a server speech service.
• Interaction and animation tuning: Tuned motion, scroll presentation, reduced-motion paths, and responsive interaction so expressive effects remain controlled rather than competing with content.
• Overlay and layout coordination: Coordinated the boot experience, navigation, cursor, scanline treatment, chat surfaces, popups, and 3D focal layer so each remains legible and reachable.
• Localization and content: Built the nine-locale MDX workflow, English fallback, translation messages, route-aware metadata, and shared project-document presentation.
• MCP and security: Implemented the read-only agent surface, OAuth, discovery design, same-origin chat boundary, and temporary signed-lockdown protection.
• Supporting product systems: Integrated contact, Spotify, analytics choice, accessibility behavior, and human or LLM-readable documentation as part of the product.

Project Architecture

This app follows a modular feature-based Next.js App Router pattern, with localized routes and content separate from interactive or integration-specific concerns.

• Layered Structure: Server components handle locale and document structure; client components handle browser interaction. API routes expose chat, contact, media, and MCP capabilities behind deliberate service and security boundaries.
• Application and content map: app contains locale routes, APIs, and discovery documents; components contains sections, UI, chatbot, providers, layout, and project presentation; content/projects, data, lib, messages, i18n, stores, hooks, and styles each retain a focused ownership boundary.
• Feature Modules:
  • components/sections: Hero, about, experience, skills, projects, contact, and certification composition.
  • components/ui: Reusable visual primitives including glitch, cursor, Canvas, and 3D interaction pieces.
  • components/chatbot: Oz widget, conversation UI, actions, and supporting presentation logic.
  • components/providers: Client shells plus theme, internationalization, and music-provider integration.
  • content/projects: Locale-specific MDX project documentation with English fallback.
  • messages and data: Translation messages and verified portfolio facts.
  • lib/mcp, lib/security, and lib/services: MCP transport and tools, authorization safeguards, and integration services.
  • stores: The focused chatbot filter store, rather than a broad global application store.
• State Management: NextThemesProvider manages theme preference, NextIntlClientProvider supplies locale messages, and MusicPlayerProvider owns music context. Chatbot session settings use component-local or browser storage, with one custom chatbot filter store for its narrow concern.
• Refactoring and Improvements: Next.js 16 with Turbopack supports the current development workflow. Modular boundaries let visual features, route handlers, content, and integration code evolve independently.

Route and System Structure

• PWA and SEO Infrastructure: /manifest.webmanifest, /robots.txt, /sitemap.xml, JSON-LD output, and humans.txt support installation, indexing, and human-readable discovery.
• Nine-Locale Routing: /[locale], localized privacy and terms pages, /[locale]/ignore-analytics, and /[locale]/projects/[slug] provide the nine supported locales. There is no catch-all locale route.
• MCP and AI Agent Surface: /.well-known discovery documents, agent cards and skills, /openapi.json, OAuth endpoints, /api/mcp, health, and legacy SSE or message compatibility routes support read-only agent access.
• Oz, Contact, and Media: /api/chat, /api/chat/health, /api/contact, /api/gallery/[slug], /api/spotify/login, its callback, and now-playing routes support the assistant, contact, project galleries, and Spotify experience.
• Human and LLM Context Exports: /llms.txt, /llms-full.txt, /auth.md, plus humans and discovery documents provide concise machine and human context.
• Content path: Project MDX is selected from the locale and slug, then rendered with shared project components so documentation remains part of the site rather than a separate knowledge base.
• Operational path: Secrets remain server-side, contact delivery is handled through SMTP, and Spotify authentication follows its dedicated login and callback flow.
• Analytics choice: Visitors can use the localized opt-out path, while the product still has an operational signal for aggregate observation when analytics are enabled.
• Public routes: Legal, privacy, project, discovery, and system endpoints have distinct responsibilities instead of relying on a fictional catch-all page.
• Agent scope: MCP tools expose verified portfolio reading only. They are intentionally separated from visitor chat actions and protected resources.
• Media scope: Spotify controls are supplied through the dedicated provider and route handlers, so music UI does not become an unbounded global application service.
• Contact scope: The contact endpoint keeps mail delivery behind an SMTP integration boundary and applies appropriate submission protections.
• Visual scope: Canvas and WebGL enhance focal moments while the core story remains useful on devices that reduce motion or lack fine pointer input.
• Maintenance scope: Shared components render the document shape, while the MDX files remain the owned editorial record for each project locale.
• Release scope: Runtime and dependency configuration are validated through the same build workflow that prepares the deployed site.
• Documentation scope: Human-readable and LLM-readable exports describe the product without substituting private implementation access.

Demo Preview

• Digital Glitch Landing Page: A focused home view pairs clear typography, terminal-inspired status language, texture, and responsive visual layers.
• Interactive AI Chatbot: Oz streams contextual assistance, can surface approved UI actions, and can optionally use local browser voice feedback.
• Optional Voice and Dubbing Feedback: Compatible browsers can present user-controlled local audio feedback and a dubbing popup without making sound necessary to use the site.
• Bento and high-density presentation: Projects, skills, experience, and credentials are arranged into readable high-information layouts rather than isolated marketing cards.
• Localized project detail: Each locale can present the same architecture and contribution narrative in the language chosen by the visitor.
• Agent-ready context: The documented OAuth and discovery surface shows how controlled machine access can coexist with a public human-facing portfolio.

Hosting note: This codebase is the documented live portfolio at franzdomingo.dev.