Enterprise Dashboard SaaS

An elegant, robust, and highly secure multi-page Enterprise Dashboard SaaS application. Built with Vue 3 (Composition API), TypeScript, Vite, Tailwind CSS v4, Pinia, Radix Vue, and fully tested using Vitest on a robust virtual environment.

---

🏗️ Architectural Overview

The application follows a clean, decoupled, full-stack ready architecture. The client-side is a high-performance Single Page Application (SPA) structured with reactive state management, validation layers, dynamic routing guards, and modular composables.

📊 System Architecture & Data Flow

                      ┌────────────────────────────────────────┐
                      │             Web Browser                │
                      │  (Iframe or Standalone Tab Viewport)   │
                      └──────────────────┬─────────────────────┘
                                         │
                         [HTTPS / WS (HMR Disabled)]
                                         │
                                         ▼
                      ┌────────────────────────────────────────┐
                      │          Vite Server (Port 3000)       │
                      │  - Handles Asset Resolution            │
                      │  - Proxies '/api' -> Port 8000         │
                      └──────────────────┬─────────────────────┘
                                         │
                                         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            Vue 3 Client Engine                              │
│                                                                             │
│  ┌───────────────────────┐  ┌───────────────────────┐  ┌─────────────────┐  │
│  │     Vue Router        │  │     Pinia Store       │  │  Vee-Validate   │  │
│  │  - Navigation Guards  │  │  - Global State       │  │  - Form Schema  │  │
│  │  - Route Protection   │  │  - Auth state ('auth')│  │  - Validation   │  │
│  └──────────┬────────────┘  └───────────┬───────────┘  └────────┬────────┘  │
│             │                           │                       │           │
│             ▼                           ▼                       ▼           │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                             Pages & Views                             │  │
│  │  - Auth: Login, Register, VerifyEmail                                 │  │
│  │  - Dashboard: Analytics (Data Tables & Charts), Home, Profile         │  │
│  └──────────────────────────────────────┬────────────────────────────────┘  │
│                                         │                                   │
│                                         ▼                                   │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                           Custom UI System                            │  │
│  │  - Radix Vue primitives (Tabs, Dropdowns)                             │  │
│  │  - Tailwind CSS v4 styling system                                    │  │
│  │  - Modular animations via Motion One                                  │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

🧬 Directory Layout & Module Roles

src/
├── __tests__/          # Multi-layer testing suite
│   ├── unit/           # Store & helper logic validation
│   ├── components/     # UI rendered template & interaction tests
│   └── e2e/            # Simulated client-side router navigation flows
├── components/         # Highly decoupled custom components
│   └── ui/             # Radix Vue primitives + Tailwind-wrapped reusable components
├── composables/        # Business logic encapsulated in reactive hook modules
├── layouts/            # Global page wrapping structures (e.g. DashboardLayout.vue)
├── lib/                # Clean core functions & standard helper integrations
├── router/             # Vue Router instantiation & route-protection guards
├── stores/             # Pinia state engines (Auth & user sessions)
└── views/              # View layer matching specified routes (Auth & Dashboard)

---

🌟 Key Features & Functional Modules

1. 🔐 Security & Complete Authentication Suite

• Decoupled Auth State: Backed by a Pinia store (auth.ts) which manages login statuses, authenticated user attributes, and state persistence.
• Secure Helper Modules: Utilizes custom browser helper scripts (authHelpers.ts) to manage tokens, parse JWT properties, handle mock authorizations, and safely expire authentication tokens.
• Form Validation: Forms (Login, Registration, etc.) are built with vee-validate to enforce robust field criteria (email patterns, password lengths, standard entries) dynamically.
• Dynamic Route Protection: Navigational Guards dynamically inspect credentials. Unauthenticated users seeking to view dashboard features (such as /profile or /analytics) are gracefully redirected to /login, while already logged-in users are redirected away from login screens back to their active session dashboard.

2. 📊 Enterprise Analytics & Interactive Metrics

• SVG-powered Charts: Modular SVG renderings that provide accurate visual telemetry of system resources, server usage, active sessions, and core SaaS indicators.
• Responsive Data Tables: Detailed grids listing user accounts, statuses, countries, and action items, optimized for desktop and mobile viewport ratios.
• Dynamic Data Filters: Filter through data elements to visualize changes in real-time, matching standard SaaS metrics tools.

3. ⚙️ Interactive Profile Settings

• Decoupled Tab Layouts: Leverages custom Radix Vue structures (Tabs, TabsList, TabsTrigger, TabsContent) to organize profile sections cleanly into:
  • General: Pre-populated profile edits including names, email addresses, and contact parameters.
  • Security: Interactive password resets containing password strength checkers and reactive requirement checkmarks.
  • Notifications: High-contrast toggles configuring newsletter updates, alerts, and system telemetry reporting.
• International Phone Inputs: Seamlessly integrated with intl-tel-input featuring fully searchable country dials, flag icons, and area-specific auto-formatting.
• Password Strength Meter: A reactive checklist testing uppercase letters, lowercase letters, numbers, and special characters. It grades input strings into Empty ➔ Weak ➔ Medium ➔ Strong classifications with responsive background meter states.

4. 🎨 Crafted Professional Design System

• Tailwind CSS v4 Integration: Uses the newest @tailwindcss/vite engine inside Vite config to manage styling dynamically.
• High Contrast Layouts: Soft off-whites, neutral deep charcoal grays, crisp text, and clean negative space to present an eye-safe, professional atmosphere.
• Smooth Motion & Transitions: Utilizes motion and Vue transit blocks to handle subtle fade-ins, sliding panels, and hover feedback.

5. 🌐 OpenTelemetry Monitoring & Observability

• Unified Tracing, Metrics, and Logs: Integrates a complete, standard OpenTelemetry (v2.x) client-side instrument framework initialized on startup (otel.ts).
• Automatic HTTP/Fetch Instrumentation: Automatically intercepts and traces all outgoing AJAX/HTTP request dependencies (fetch and XMLHttpRequest) via auto-instrumentation packages.
• Real-time Observability Fallbacks: Features active console exporters for traces, metrics (periodic reports), and logs, ensuring live developer feedback during local testing.
• Production OTLP Collectors ready: Supports seamless forwarding of traces, metrics, and logs to any compliant OpenTelemetry collector endpoint simply by defining VITE_OTEL_EXPORTER_OTLP_ENDPOINT in your environment.
• Declarative Helpers: Exposes global telemetry API helpers:
  • trackSpan(name, fn, attributes): Wrap critical function runs in active telemetry spans.
  • logInfo(), logWarn(), logError(): Emit severity-aware logging telemetry.
  • incrementCounter(name, value, description, attributes): Record business & system metrics (e.g., auth success/failure rates).

---

⚡ Tech Stack

Technology	Purpose
Vue 3	Frontend framework using standard Composition API (Script Setup)
TypeScript	Type-safety, automated code intelligence, interfaces
Vite	Hyper-fast module bundler with custom HMR settings
Tailwind CSS v4	CSS utility system for high-performance visual crafting
Pinia	Client state container supporting persistent storage
Radix Vue	Unstyled, fully accessible primitives for UI components
Vee-Validate	Declarative form validations and active schema matching
Vitest	Native Vite-powered unit and integration testing engine
Happy DOM	High-performance, lightweight browser emulator for tests
Lucide Vue Next	Crisp, lightweight, uniform vector iconography

---

🛠️ Getting Started & Local Development

Prerequisites

Make sure you have Node.js (v18 or higher) and npm installed on your machine.

Installation

Clone the repository and install all dependencies:

npm install

Run Local Development Server

Launch the development server on the dedicated workspace port (3000):

npm run dev

Open http://localhost:3000 in your browser to view the application.

Build and Compile for Production

Creates a highly optimized production build output inside the dist/ folder:

npm run build

Static File Preview

Review the local build outputs locally before deployment:

npm run preview

Linting

Validate codebase syntax, verify typescript compilations, and catch fatal errors:

npm run lint

---

🧪 Testing Architecture

This repository contains a robust, comprehensive testing suite powered by Vitest and Vue Test Utils, validating state, view logic, and route navigation.

To run the complete test suite:

npm run test

Test Classifications

1. Unit Tests (src/__tests__/unit/)
   • authHelpers.spec.ts: Validates cookie parsing, token storage, deletion, JWT parsing safety, and session expiration calculation.
   • authStore.spec.ts: Validates Pinia global auth states, verifying proper log-in credentials processing and session clears.
   • otel.spec.ts: Verifies complete OpenTelemetry core utilities initialization, traces span creation, logs record emission, and metrics logging indicators.
2. Component Tests (src/__tests__/components/)
   • Login.spec.ts: Tests the Login view rendering, validating fields, throwing form errors via vee-validate, mocking backend axios failures, and asserting successful redirect triggers.
   • Profile.spec.ts: Flattens Radix Vue Tab Content wrappers to test General fields, invalid form updates, and password criteria strength checklists dynamically.
3. Simulated End-to-End Tests (src/__tests__/e2e/)
   • authFlow.spec.ts: Validates complete routing and navigation guard security loops under a clean happy-dom environment, including:
     • Redirection of unauthenticated guest users attempting to view secure routes.
     • Access permissions of logged-in sessions and redirection away from auth screens.
     • Logout operations and clean route resets.

---

📝 Customization & Core Instructions

To configure custom global rules, development instructions, or custom AI actions for this project:

• Add configuration profiles inside the AGENTS.md or GEMINI.md files at the workspace root.
• These rules are dynamically loaded on developer runs to keep code standards perfect.