🏗️ Architecture Guide

This guide documents the architecture and implementation of the ICJIA Safe From the Start application, a Vuetify 3 + Nuxt 4 static-generated web application.

Tech Stack

Technology	Purpose
Nuxt 4	Static generation, Vue 3 support, excellent DX, auto-imports
Vue 3	Modern reactive framework, composition API
Vuetify 3	Material Design components with accessibility features
Nuxt Content 3	File-based CMS, markdown support
TypeScript	Type safety, better IDE support
Vitest	Unit and integration testing
axe-core	Accessibility testing engine

Project Structure

/
├── app/                          # Nuxt application code
│   ├── components/              # Reusable Vue components
│   │   └── content/             # Content-specific components
│   ├── composables/            # Vue composables (reusable logic)
│   │   └── states.ts           # Global state management
│   ├── pages/                  # Route pages (file-based routing)
│   ├── plugins/                # Nuxt plugins
│   └── utils/                  # Utility functions
├── content/                     # Markdown content files
├── public/                      # Static assets
│   └── docs/                   # Documentation portal
│       ├── accessibility/      # Accessibility audit reports
│       ├── architecture/       # Architecture documentation
│       ├── jsdoc/              # API documentation
│       └── tests/              # Test reports
├── scripts/                     # Build and utility scripts
├── test/                        # Test suites
│   ├── unit/                   # Unit tests
│   └── nuxt/                   # Nuxt environment tests
├── creators/                    # Route and sitemap generators
└── src/json/                    # Generated JSON data

Key Features

Static Site Generation (SSG)

The application uses Nuxt's static generation for optimal performance:

Pre-rendered HTML for all routes
Fast initial load times
CDN-friendly deployment
SEO optimized with full HTML content

Accessibility

WCAG 2.1 AA compliance is verified through automated testing:

Desktop viewport (1920×1080)
Tablet viewport (768×1024)
Mobile viewport (375×667)
Automated axe-core scanning

Documentation Portal

Self-contained documentation at /docs/:

Accessibility audit reports
Architecture documentation
API documentation (TypeDoc)
Test results and coverage

Development Commands

# Start development server (port 8000)
yarn dev

# Generate static site
yarn generate

# Run all tests with HTML report
yarn test:all

# Run accessibility audit (requires dev server)
yarn audit:a11y:full

# Generate API documentation
yarn docs:jsdoc

# Run all documentation generation
yarn docs:all

Build Process

The build pipeline automatically:

Clears cache directories
Generates page routes
Creates sitemap.xml
Ensures documentation placeholders exist
Runs Nuxt static generation

State Management

Global state is managed through Nuxt's useState composables:

// app/composables/states.ts
export const useNavToggle = () => useState<boolean>('nav', () => false)
export const useCounter = () => useState<number>('counter', () => 0)
export const useColor = () => useState<string>('color', () => 'pink')

Deployment

The application is deployed to Netlify with the following configuration:

# netlify.toml
[build]
  command = "yarn generate"
  publish = ".output/public"

[build.environment]
  NODE_VERSION = "22"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200