portfolio/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2026-04-07

Pattern Overview

Overall: Vue 3 SPA (Single Page Application) with component-based architecture and SSR-friendly design patterns

Key Characteristics:

• Client-side routing with lazy-loaded views for performance optimization
• Composition API-based composables for shared logic and state management
• Global state managed via Pinia stores
• Multi-language support with vue-i18n
• Theme switching with localStorage persistence
• SEO-optimized with dynamic meta tags and structured data
• Google Analytics and GTM integration for tracking

Layers

Presentation Layer (Components):

• Purpose: Render UI and handle user interactions
• Location: src/components/
• Contains: Vue Single File Components organized by domain (layout, sections, shared, testimonials, icons)
• Depends on: Composables for data access and side effects, Router for navigation
• Used by: Views and other components

View Layer (Pages):

• Purpose: Page-level component assembly and routing targets
• Location: src/views/
• Contains: Full page components (HomePage, ProjectsPage, ContactPage, AboutPage, FiverrPage, FormationPage, ProjectDetailPage)
• Depends on: Composables (useSeo, useI18n, useProjects), components, data stores
• Used by: Router for navigation

Business Logic Layer (Composables):

• Purpose: Encapsulate reusable logic, data fetching, and side effects
• Location: src/composables/
• Contains: Vue composables for projects, SEO, i18n, themes, galleries, date formatting, assets, site config
• Depends on: Types, stores, external libraries (vue-router, vue-i18n)
• Used by: Components and views

Data/State Layer (Stores & Data):

• Purpose: Global state and static data management
• Location: src/stores/, src/data/
• Contains: Pinia stores, static project data, testimonials, tech stack, FAQs
• Depends on: Types, composables (useI18n for localized data)
• Used by: Composables and components

Configuration Layer:

• Purpose: Application-wide settings and configuration
• Location: src/config/, src/router/, src/i18n/
• Contains: Site configuration, router setup, i18n initialization, locale messages
• Depends on: Types, data
• Used by: Main entry point and throughout app

Type Definitions:

• Purpose: TypeScript interfaces and types
• Location: src/types/index.ts
• Contains: Project, Technology, TechStack, SocialLink, ContactInfo, FiverrService, SiteConfig interfaces

Data Flow

1. Initial Page Load:

1. index.html loads with embedded Google Analytics and Google AdSense scripts
2. src/main.ts initializes Vue app, Pinia store, router, and i18n
3. src/App.vue applies theme from localStorage and renders AppHeader + RouterView + AppFooter
4. Router initializes and loads HomePage or requested route
5. useTheme() applies saved theme class to document
6. useI18n() loads saved locale from localStorage

2. Route Navigation:

1. User clicks link or navigates directly
2. Router's beforeEach hook updates document title and meta description from route.meta
3. Router's afterEach hook triggers scroll to top and Google Analytics page view tracking
4. Target view component mounts and runs useSeo() for SEO metadata
5. View renders child components with fetched data
6. Components subscribe to composables for reactive data

3. Data Access Pattern (Example: Projects):

1. Component imports useProjects() composable
2. Composable accesses base project data from src/data/ or static store
3. Composable uses useI18n() to localize strings
4. Component receives computed reactive projects array
5. Component renders with v-for or passes data to child components

4. Theme Switching:

1. ThemeToggle component toggles isDark ref in useTheme()
2. Watch handler applies class to document.documentElement
3. Watch handler saves to localStorage
4. Browser CSS respects dark class on document

5. Language Switching:

1. LanguageSwitcher component calls switchLocale() from useI18n()
2. vue-i18n locale updates and all {{ t() }} expressions re-evaluate
3. New locale saved to localStorage
4. Computed properties like homeFAQs in HomePage.vue re-evaluate with new translations

State Management:

• Global: Pinia stores (currently minimal - useCounterStore exists but unused)
• Composable State: Reactive refs in composables (theme, locale, gallery state)
• Component State: Local reactive refs for UI state (menu toggle, form inputs)
• Persistence: localStorage for theme and locale preferences
• Server-Side Data: Static JSON-like data in src/data/ files, not fetched from API

Key Abstractions

useI18n() Composable:

• Purpose: Unified i18n access with convenience methods
• Examples: src/composables/useI18n.ts
• Pattern: Wraps vue-i18n's useI18n(), adds locale switching and computed locale state
• Usage: Available in all components via injection

useSeo() Composable:

• Purpose: Dynamic SEO tag management for SPA
• Examples: src/composables/useSeo.ts
• Pattern: Lifecycle hooks to create/remove meta tags on mount/unmount, prevents tag duplication
• Usage: Called in view components with options object for title, description, OG tags, structured data

useProjects() Composable:

• Purpose: Project data access with localization
• Examples: src/composables/useProjects.ts
• Pattern: Base data stored separately, computed properties merge translations on read
• Usage: Returns computed projects array that updates when language changes

useTheme() Composable:

• Purpose: Centralized theme state and persistence
• Examples: src/composables/useTheme.ts
• Pattern: Reactive boolean with computed getter, watch for persistence, DOM manipulation
• Usage: Injected globally in App.vue, consumed by ThemeToggle component

TechStack Interface:

• Purpose: Typed structure for technology categories
• Examples: src/types/index.ts
• Pattern: Categorized array structure (programming, front, database, devtools, operating_systems, socials)
• Usage: Imported in src/data/techstack.ts and AboutPage.vue

SiteConfig:

• Purpose: Single source of truth for site-wide settings
• Examples: src/config/site.ts
• Pattern: Exported constant object with typed structure, includes contact info, social links, SEO config
• Usage: Imported where needed for links, contact info, performance settings

Entry Points

HTML Entry Point:

• Location: index.html
• Triggers: Browser page load
• Responsibilities: Define DOM root (#app), load analytics/ads scripts, include meta tags, defer main.ts loading

Application Entry Point:

• Location: src/main.ts
• Triggers: After HTML DOM ready
• Responsibilities: Create Vue app, install plugins (Pinia, Router, i18n), mount to #app

Router Entry Point:

• Location: src/router/index.ts
• Triggers: App.use(router) in main.ts
• Responsibilities: Define route table, implement beforeEach/afterEach hooks for SEO and analytics

Root Component:

• Location: src/App.vue
• Triggers: After Vue app mounts
• Responsibilities: Initialize theme, render layout structure (header + router-view + footer), handle route-change scroll behavior

View Components:

• Location: src/views/*.vue
• Triggers: Router navigation to matching path
• Responsibilities: Page-specific SEO setup via useSeo(), compose sections and content, manage page-level state

Error Handling

Strategy: Graceful degradation with fallback content; no explicit error boundaries detected

Patterns:

• Lazy-loaded routes with no 404 component (TODO comment in router) - currently redirects to HomePage
• SEO composable safely creates/finds meta elements before updating
• Theme fallback to 'dark' if localStorage empty
• Locale fallback to 'en' if not in localStorage
• Gallery modal (GalleryModal.vue) handles missing images gracefully
• Contact form likely has validation but not visible in read scope

Cross-Cutting Concerns

Logging: Console-based or via external services - no custom logger detected; development uses Vue DevTools plugin

Validation: Form validation in components (ContactPage uses validation likely); no centralized validation layer

Authentication: No built-in auth system - portfolio is public facing; new auth stores/views added (LoginView, RegisterView, VerifyEmailView, DashboardView, ForgotPasswordView, guards.ts) but not integrated into main router

SEO: Centralized via useSeo() composable and router hooks; dynamic meta tags, Open Graph, Twitter cards, structured data; Google Analytics via gtag in router afterEach; Umami analytics via deferred script tag in index.html

Performance: Code splitting via lazy routes, vendor chunk separation in vite.config.ts, CSS code splitting enabled, Terser minification, webp image support configured, lazy image loading configurable in siteConfig

Accessibility: ARIA labels on interactive elements (AppHeader navigation, buttons); semantic HTML (header, nav, main, section roles); focus styles defined in App.vue

---

Architecture analysis: 2026-04-07