Skip to content
BranchesTags

Repository files navigation

💻 Drive AI Client Application — System Architecture Specification

📑 Table of Contents

  1. Executive Summary
  2. UI/UX Architecture & Component Hierarchy
  3. Global State Architecture (Zustand Store Slices)
  4. Interactive Component Specifications
  5. Networking & API Integration Strategy
  6. Design System & Styling Tokens
  7. Performance, Accessibility & Security Optimizations
  8. Exhaustive Code Base Directory Structure
  9. Developer Operations & Testing Guide

1. Executive Summary

The Drive AI Client Application is a high-performance single-page web interface built on Next.js (App Router Architecture), TailwindCSS, and Zustand. It renders an interactive Google Drive workspace integrated with real-time AI tools:

  • Google Drive Workspace Experience: Supports drag-and-drop navigation, dynamic Grid/List view switching, nested folder trees, search filtering, and multi-item batch operations.
  • Real-Time Visual Upload Tracking: A floating status widget tracks multi-file upload progress sequentially through real-time job status tags (PENDING, UPLOADING, INDEXING, DONE, FAILED).
  • Grounded AI Copilot Drawer: An interactive slide-in panel offering voice dictation, conversation threads, citation cards, and file-scoped Q&A context.
  • One-Click Translation: An interactive modal allowing users to translate documents into 13 target languages and export them as PDF, DOCX, or TXT files.

1.1 Complete Frontend Technology Stack Specification

Category Technology Version Purpose in Client Architecture Selection Rationale & Advantage
Framework & Engine Next.js (App Router) ^15.1.0 Client Framework & Server Rendering Provides automatic route optimization, layout composition, server-side font optimization (next/font), and React Server Components support.
UI Library React ^19.0.0 UI Component Engine Declarative component model utilizing custom hooks (useState, useEffect, useCallback, useRef) for smooth reactivity.
Language TypeScript ^5.7.3 Type-Safe Architecture Guarantees strict compile-time verification across Zustand stores, API payload DTOs, and component props interfaces.
State Management Zustand ^5.0.0 Global State Slices Engine Unopinionated, lightweight store manager using atomic slices (useDriveStore, useAiStore, useAuthStore) without Context Provider wrapper boilerplate or unnecessary re-renders.
Styling & Theme TailwindCSS ^3.4.1 Utility-First Styling System Rapid development utility classes coupled with custom design tokens for glassmorphism, responsive breakpoints, and dark mode themes.
Vanilla CSS Tokens CSS3 Variables Core Color & Theme Variables CSS variables defining HSL custom surface values, backdrop blurs, slide-in transitions, and card container states.
API Client Adapter Axios ^1.7.9 HTTP Communications Gateway Intercepts all outgoing requests to inject JWT Bearer Authorization headers automatically while standardizing error handling.
Icons & Design Assets Lucide React ^0.474.0 Vector UI Component Icons Lightweight, consistent vector graphics rendered directly as React component SVGs.
Notifications Sonner ^1.7.2 Non-Blocking Toast Provider Stackable toast notifications for tracking upload status, download completions, and server exceptions.
Audio Capture HTML5 MediaRecorder Browser Native Microphone Audio Stream Dictation Captures microphone audio streams (.webm) directly in the browser for voice-to-text dictation.
Testing Suite Vitest ^4.1.10 Vite-Powered Unit Test Runner Ultra-fast unit testing runner executing component mocks and store slice tests.

2. UI/UX Architecture & Component Hierarchy

graph TD
    %% Main Layout Root
    subgraph Dashboard Viewport [Next.js App Router: /dashboard/page.tsx]
        SearchHeader[SearchHeader Component]
        Sidebar[Sidebar Component]

        subgraph Canvas Workspace [Workspace Canvas Engine]
            Toolbar[Toolbar Action Bar]
            Explorer[ExplorerPane Component]

            subgraph Explorer Components [Explorer Layout Modes]
                GridView[Grid View Canvas]
                ListView[List View Table]
                CommandBar[Floating Bulk Command Bar]
            end
        end

        subgraph Floating Overlays [Floating Utility Layers]
            UploadWidget[Floating Upload Progress Widget]
            CopilotDrawer[AiCopilotDrawer Slide-in Panel]
            TranslateModal[TranslateModal Overlay]
            ConfirmModal[ConfirmDialog Overlay]
        end
    end

    %% State Orchestration
    DriveStore[(Zustand: useDriveStore)]
    AiStore[(Zustand: useAiStore)]
    AuthStore[(Zustand: useAuthStore)]

    Explorer -->|Updates Checked Set| DriveStore
    DriveStore -->|Controls Visibility| CommandBar
    Explorer -->|Attaches File & Opens Drawer| AiStore
    AiStore -->|Controls Visibility| CopilotDrawer
    Explorer -->|Opens Translation Options| TranslateModal
Loading

3. Global State Architecture (Zustand Store Slices)

To prevent component re-rendering issues, global client state is organized into modular Zustand store slices:

                          ┌────────────────────────┐
                          │   Zustand Store Root   │
                          └───────────┬────────────┘
                                      │
         ┌────────────────────────────┼────────────────────────────┐
         │                            │                            │
         ▼                            ▼                            ▼
┌──────────────────┐        ┌──────────────────┐        ┌──────────────────┐
│  useDriveStore   │        │    useAiStore    │        │   useAuthStore   │
├──────────────────┤        ├──────────────────┤        ├──────────────────┤
│ - folderUuid     │        │ - isDrawerOpen   │        │ - token          │
│ - selectedUuids  │        │ - activeFileUuid │        │ - user           │
│ - activeTab      │        │ - activeFileName │        │ - isAuthenticated│
│ - viewMode       │        │ - chatMessages   │        └──────────────────┘
│ - searchQuery    │        │ - isRecording    │
└──────────────────┘        └──────────────────┘

1. useDriveStore

Manages directory navigation, selection sets, and workspace filters:

  • currentFolderUuid: Active directory UUID (null for root).
  • selectedUuids: Set<string> containing currently checked file and folder UUIDs.
  • activeTab: Workspaces scope ("drive" | "trash" | "starred").
  • viewMode: Visualization format ("grid" | "list").
  • searchQuery: String query used for real-time item name filtering.

2. useAiStore

Manages the AI Copilot side-drawer panel and conversational contexts:

  • isDrawerOpen: Boolean controlling drawer slide-in positioning.
  • activeFileUuid / activeFileName: Stores the file currently locked to conversation context.
  • chatMessages: Array of thread objects containing messages, timestamps, and citation sources.
  • openDrawerForFile(fileUuid, fileName): Atomically locks the active file context and opens the drawer.

3. useAuthStore

Manages JWT tokens and identity session states persisted across reloads.

4. Interactive Component Specifications

4.1 Floating Sequential Upload Progress Widget

Located at bottom-22 right-6, this widget provides feedback during multi-file uploads:

┌──────────────────────────────────────────────────────────┐
│  Uploading 3 items                            [ _ ] [ X ]│
│  ████████████████████████████░░░░░░░░░░░░░░░  66%        │
├──────────────────────────────────────────────────────────┤
│  📄 project_proposal.pdf                 [ INDEXING ]    │
│  📊 financial_report.xlsx                [ UPLOADING ]   │
│  🖼️ architecture_diagram.png             [ PENDING  ]    │
└──────────────────────────────────────────────────────────┘
  • Sequential Execution: Posts files sequentially via Axios to maintain responsive UI feedback.
  • Live Status Tag Machine:
    • PENDING: Waiting in upload queue.
    • UPLOADING: Binary bytes streaming to backend gateway.
    • INDEXING: Backend is parsing text and generating vector embeddings.
    • DONE: Successfully saved and indexed.
    • FAILED: Error occurred (e.g. format rejection).

4.2 Multi-File Selection & Floating Bulk Command Bar

  • Checkboxes: Checked items display checkboxes on hover (Grid view) or inline table rows (List view).
  • Master Select-All Header: List view table header features an indeterminate checkbox.
  • Global Workspace Select-All: A Select All / Deselect All action button in the header selects or clears all visible files and folders across both Grid and List modes.
  • Floating Command Bar: Positioned at bottom-6 left-1/2 -translate-x-1/2:
┌──────────────────────────────────────────────────────────────┐
│  3 items selected   │ [Move to Trash] [Restore] [Cancel (X)] │
└──────────────────────────────────────────────────────────────┘

4.3 Speak to Chat (HTML5 Voice Dictation Engine)

Implemented inside AiCopilotDrawer:

sequenceDiagram
    autonumber
    actor User
    participant Component as AiCopilotDrawer Component
    participant Media as Browser MediaRecorder API
    participant API as POST /ai/transcribe Endpoint

    User->>Component: Click Microphone Icon
    Component->>Media: navigator.mediaDevices.getUserMedia({ audio: true })
    Media-->>Component: Audio Stream Active
    Component->>Component: Update UI (pulsing red stop button)

    User->>Component: Click Stop Button
    Component->>Media: mediaRecorder.stop()
    Media-->>Component: Audio Blob (.webm)
    Component->>API: Post FormData(audioBlob)
    API-->>Component: { text: "Summarize this document" }
    Component->>Component: Automatically populate chat input field
Loading

4.4 One-Click Document Translation & Packaging Modal

TranslateModal.tsx provides an interface to translate and export documents:

  • Selected File Name: Displays target file title.
  • Target Language Selector: Choice of 13 languages (Hindi, English, Spanish, French, German, Italian, Japanese, Chinese, Marathi, Tamil, Telugu, Kannada, Bengali).
  • Export Format Selector: PDF (.pdf), DOCX (.docx), or TXT (.txt).
  • Auto-Refresh: Triggers onSuccess() to refresh directory files upon completion.

4.5 Document-Specific AI Context Attachment Engine

When a user selects "Ask AI" on any file:

  1. openDrawerForFile(fileUuid, fileName) opens the side drawer.
  2. A file tag is rendered above the chat composer:
┌──────────────────────────────────────────────────────────┐
│  📄 financial_audit.pdf [✕]                             │
│ ┌───────────────────────────────────────┬──────────────┐ │
│ │ Ask AI a question...                  │ [🎙️]  [ Send]│ │
│ └───────────────────────────────────────┴──────────────┘ │
└──────────────────────────────────────────────────────────┘
  1. Submitting queries passes fileUuid in the POST body to /ai/chat. The backend scopes the RAG vector search exclusively to that document.
  2. Clicking [✕] clears activeFileUuid and activeFileName, returning the chat to general workspace mode.

5. Networking & API Integration Strategy

API calls are routed through a centralized Axios client (src/lib/axios.ts):

// Automatic JWT Bearer Token Injection
api.interceptors.request.use((config) => {
  const token = useAuthStore.getState().token;
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});
  • Error Handling: Handles errors using Sonner toast notifications: 
    toast.error(err.response?.data?.message || "Failed to process request");

6. Design System & Styling Tokens

The application uses TailwindCSS utilities with custom CSS variables (src/app/globals.css):

:root {
  --background: #090d16;
  --surface: #111827;
  --surface-hover: #1f2937;
  --card: #131b2e;
  --border: #1f293d;
  --foreground: #f9fafb;
  --muted-foreground: #9ca3af;
  --primary: #6366f1;
}

Visual Effects:

  • Glassmorphic Overlays: backdrop-blur-md bg-card/80 border border-border/50 shadow-2xl
  • Animations: Fluid slide-in panels (animate-in fade-in slide-in-from-right-4 duration-300) and soft pulse glows.

7. Performance, Accessibility & Security Optimizations

  1. Virtual DOM Cleanup: Clears audio tracks and blob streams on component unmount.
  2. Keyboard Accessibility: Supports ESC key bindings to close active modals.
  3. Event Propagation Safety: Uses e.stopPropagation() on context buttons to avoid unwanted file downloads or parent selections.

8. Exhaustive Code Base Directory Structure

p-1-frontend/
├── src/
│   ├── app/
│   │   ├── globals.css             # Design tokens & dark theme variables
│   │   ├── layout.tsx              # Root HTML wrapper and font providers
│   │   ├── page.tsx                # Landing redirection controller
│   │   ├── (auth)/
│   │   │   └── login/page.tsx      # Secure Login view page
│   │   └── (dashboard)/
│   │       └── dashboard/page.tsx  # Core workspace canvas & upload status manager
│   ├── features/
│   │   ├── auth/components/        # Login/Signup forms
│   │   └── drive/
│   │       ├── types.ts            # Frontend data structures
│   │       └── components/
│   │           ├── Sidebar.tsx     # Directory tree navigation
│   │           ├── SearchHeader.tsx# Header query input
│   │           ├── Toolbar.tsx     # View mode toggles
│   │           ├── ExplorerPane.tsx# Grid/List file canvas & command bar
│   │           ├── AiCopilotDrawer.tsx # Chat drawer & voice dictation
│   │           ├── TranslateModal.tsx  # Document translation dialog
│   │           ├── ShareModal.tsx      # Sharing & public link generator
│   │           ├── ConfirmDialog.tsx   # Destruction warning dialogs
│   │           └── AuditPane.tsx       # System activity logs
│   ├── lib/
│   │   ├── axios.ts                # Axios client with JWT interceptor
│   │   └── logger.ts               # Component log formatter
│   └── store/
│       ├── authStore.ts            # Authentication state slice
│       ├── driveStore.ts           # Selection sets & directory state slice
│       └── aiStore.ts              # Drawer & file attachment state slice

9. Developer Operations & Testing Guide

1. Environment Setup (.env.local)

# 🌐 Server & Connection Config
PORT=3000
NODE_ENV=development

# 🔍 Logging Configuration (debug, info, warn, error)
NEXT_PUBLIC_LOG_LEVEL="debug"

# 🔌 Backend API Connection (Exposed to Client Side)
# Next.js requires NEXT_PUBLIC_ prefix to expose variables to browser code
NEXT_PUBLIC_API_URL="http://localhost:7001" // or you backend url

# 🕒 Localization Settings
NEXT_PUBLIC_DEFAULT_TIMEZONE="Asia/Kolkata"

2. Developer Server Startup

# Install dependencies
npm install

# Start Next.js development server
npm run dev

Open http://localhost:3000 to launch the workspace dashboard.

3. Testing & Code Auditing

# Run Vitest test runner (26 unit tests)
npm test

# Run ESLint quality audit
npx eslint src/

📬 Contact & Contribution

Contributions, issues, and feature requests are welcome! Feel free to check out the repository or reach out:

About

p-1-frontend.vercel.app

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages