Application Architecture

Overview

A Vue.js 3 + TypeScript application for managing inventories of items, specifically designed for museums and cultural institutions. The application provides comprehensive CRUD operations for reference data (contexts, countries, languages, projects), and museum data (items, collections, images).

Technology Stack

Application Structure

src/
├── components/           # Reusable UI components
│   ├── format/          # Data formatting components
│   ├── global/          # Global overlay components
│   ├── icons/           # Resource-specific icons
│   └── layout/          # Layout and structural components
├── composables/         # Vue composition functions
├── router/              # Vue Router configuration
├── stores/              # Pinia state management stores
├── types/               # TypeScript type definitions
├── utils/               # Utility functions
└── views/               # Page components

Authentication System

Implementation

Features

Application Template & Layout

App.vue Structure

<template>
  <div id="app" class="min-h-screen bg-gray-50">
    <AppHeader />
    <!-- Navigation and user menu -->
    <ErrorDisplay />
    <!-- Global error notifications -->
    <main>
      <RouterView />
      <!-- Page content -->
    </main>
    <AppFooter />
    <!-- Application footer -->
    <LoadingOverlay />
    <!-- Global loading spinner -->
    <DeleteConfirmation />
    <!-- Delete confirmation modals -->
    <CancelChangesConfirmation />
    <!-- Unsaved changes protection -->
  </div>
</template>

Header Features

The application uses a two-tier navigation system that must be kept in sync:

1. AppHeader.vue Navigation Menu

Dropdown-based navigation with grouped sections:

2. Home.vue Dashboard Tiles

Landing page with navigation cards organized identically to the header menu:

CRITICAL: These two navigation systems must mirror each other exactly. Each entity with a dashboard tile must have a corresponding menu item using the same icon and color.

Entity Standards

Each entity has standardized presentation across all components:

Entity Color Icon Route
Items teal ArchiveBoxIcon /items
Partners yellow UserGroupIcon /partners
Languages purple LanguageIcon /languages
Countries blue GlobeAltIcon /countries
Contexts green CogIcon /contexts
Projects orange FolderIcon /projects

Routing Configuration

Global Components

Error Display (ErrorDisplay.vue)

Loading Overlay (LoadingOverlay.vue)

Confirmation Modals

Project Resource Implementation (Reference Implementation)

Projects List View (Projects.vue)

Features

UI Components Used

Project Detail View (ProjectDetail.vue)

Three-Mode System

  1. View Mode: Read-only display with action buttons
  2. Edit Mode: Inline editing with save/cancel
  3. Create Mode: New project creation form

Features

Form Fields

Reference Data Resources (Projects, Contexts, Countries, Languages)

Implementation Status: ✅ All Four Resources Fully Implemented

All reference data resources now use consistent ListView/DetailView architecture with standardized patterns across the application.

Unified Features (Implemented Across All Resources)

  1. Consistent UI: ListView component with responsive table → card layouts
  2. Advanced Functionality: Search, filtering, sorting with smart caching
  3. Mobile Support: Responsive design optimized for all screen sizes
  4. Inline Editing: Three-mode DetailView system (view/edit/create)
  5. Loading States: Smart loading with background refresh and descriptive messages
  6. Error Handling: Centralized error management with user-friendly messages
  7. State Management: Advanced Pinia stores with reactive updates

Resource-Specific Implementations

Projects (Projects.vue → ProjectDetail.vue)

Status: ✅ Complete Implementation

Contexts (Contexts.vue → ContextDetail.vue)

Status: ✅ Complete Implementation

Countries (Countries.vue → CountryDetail.vue)

Status: ✅ Complete Implementation

Languages (Languages.vue → LanguageDetail.vue)

Status: ✅ Complete Implementation

API Integration & Client Library

API Client Configuration

// Base configuration pattern used across all stores
const createApiClient = () => {
  const baseURL =
    import.meta.env.VITE_API_BASE_URL || "http://127.0.0.1:8000/api";
  const configuration = new Configuration({
    basePath: baseURL,
    accessToken: authStore.token,
  });
  return new ResourceApi(configuration);
};

API-to-Application Feature Mapping

Authentication API (MobileAppAuthenticationApi)

API Feature Application Usage
tokenAcquire() Login functionality in auth store
tokenRefresh() Not implemented - Manual token management
tokenRevoke() Logout functionality

Project API (ProjectApi)

API Feature Application Usage
projectIndex() Projects list view data loading
projectStore() Create new project functionality
projectShow() Project detail view data loading
projectUpdate() Project editing and saving
projectDestroy() Project deletion with confirmation
projectSetEnabled() Toggle project enabled status
projectSetLaunched() Toggle project launched status
Missing: projectBulkOperations() Not implemented - Bulk project operations
Missing: projectExport() Not implemented - Project data export

Context API (ContextApi)

API Feature Application Usage
contextIndex() Context list loading with caching
contextStore() Create context via DetailView three-mode system
contextShow() Context detail view data loading
contextUpdate() Update context via inline editing
contextDestroy() Delete context with confirmation
contextSetDefault() Set default context functionality
Advanced filtering ✅ Implemented - Default context filtering

Country API (CountryApi)

API Feature Application Usage
countryIndex() Country list loading with smart caching
countryStore() Create country via DetailView system
countryShow() Country detail view data loading
countryUpdate() Update country via inline editing
countryDestroy() Delete country with confirmation
Search functionality ✅ Implemented - Real-time country search
Form validation ✅ Implemented - Country name and code validation

Language API (LanguageApi)

API Feature Application Usage
languageIndex() Language list loading with caching
languageStore() Create language via DetailView system
languageShow() Language detail view data loading
languageUpdate() Update language via inline editing
languageDestroy() Delete language with confirmation
languageSetDefault() Set default language functionality
Advanced filtering ✅ Implemented - Default language filtering

System Information API (InfoApi)

API Feature Application Usage
infoSystem() API status monitoring in composables
infoHealth() Not implemented - Health check integration
infoVersion() Not implemented - Version display

Partner API (PartnerApi)

API Status Application Status
✅ Available in client ❌ Not implemented - Planned resource

Item API (ItemApi)

API Status Application Status
✅ Available in client ❌ Not implemented - Core inventory feature

Tag API (TagApi)

API Status Application Status
✅ Available in client ❌ Not implemented - Metadata management

Picture API (PictureApi)

API Status Application Status
✅ Available in client ❌ Not implemented - Media management

Component Architecture

Layout Components

ListView Component

Purpose: Standardized list view layout for resource collections Features:

DetailView Component

Purpose: Standardized detail view for individual resources Features:

Format Components

Global Components

State Management (Pinia Stores)

Store Pattern

All stores follow consistent patterns:

Store Implementations

Project Store (project.ts)

Status: ✅ Complete Implementation

Context Store (context.ts)

Status: ✅ Complete Implementation

Country Store (country.ts)

Status: ✅ Complete Implementation

Language Store (language.ts)

Status: ✅ Complete Implementation

Auth Store (auth.ts)

Status: ✅ Complete Implementation

Global Feature Stores

Git Commit History Summary

Migration to External API Client (feature/migrate-to-external-api-client)

Initial Setup & Authentication (c05beb7 → ea3ff89)

Core Resource Implementation (6e0c8b1 → e800942)

UI Architecture Refactoring (a7eceb0 → 50c2243)

Advanced Component Development (edca074 → abc452e)

Layout Standardization (7851fa6 → 8948954)

Documentation & Code Quality (c291592 → 1a1c49b)

Advanced Features Implementation (0f8f80c → a2e6d42)

Interactive Features & Testing (2940d2f → 663d8c6)

Advanced UI Components (524e9f8 → 57de204)

Single Mode State Pattern (98fcc74 → 929a2a1)

Search & Filter Features (83b1d30 → 544a68c)

Icon Standardization & Testing (1eb4427 → eb06da8)

Code Quality & Documentation (3d50f81 → cde10c2)

Comparison: Implementation Status Across All Resources

Implementation Maturity

Feature Projects Contexts Countries Languages
Layout Component ✅ ListView/DetailView ✅ ListView/DetailView ✅ ListView/DetailView ✅ ListView/DetailView
Three-Mode System ✅ View/Edit/Create ✅ View/Edit/Create ✅ View/Edit/Create ✅ View/Edit/Create
Search Functionality ✅ Real-time search ✅ Real-time search ✅ Real-time search ✅ Real-time search
Advanced Filtering ✅ 4 filter types ✅ Default filtering ❌ No specific filters ✅ Default filtering
Responsive Design ✅ Mobile optimized ✅ Mobile optimized ✅ Mobile optimized ✅ Mobile optimized
Inline Editing ✅ Full inline editing ✅ Full inline editing ✅ Full inline editing ✅ Full inline editing
Unsaved Changes ✅ Protection enabled ✅ Protection enabled ✅ Protection enabled ✅ Protection enabled
Status Management ✅ Toggle controls ✅ Default toggle ❌ No status fields ✅ Default toggle
Loading States ✅ Smart caching ✅ Smart caching ✅ Smart caching ✅ Smart caching
Error Handling ✅ Centralized ✅ Centralized ✅ Centralized ✅ Centralized
State Management ✅ Advanced Pinia ✅ Advanced Pinia ✅ Advanced Pinia ✅ Advanced Pinia
Testing Coverage ✅ Comprehensive ✅ Comprehensive ✅ Comprehensive ✅ Comprehensive

Architectural Consistency Achievement ✅

All four core resources now demonstrate complete architectural alignment:

  1. Unified UI Patterns: All resources use ListView/DetailView components
  2. Consistent Interactions: Three-mode system implemented across all resources
  3. Responsive Design: Mobile-optimized layouts for all resource types
  4. Smart Caching: Background refresh patterns reduce loading perception
  5. Error Management: Centralized error handling with consistent user feedback
  6. State Consistency: Advanced Pinia store patterns across all resources

Completed Implementation Goals

✅ High Priority Features (Complete)

✅ Enhanced Features (Complete)

✅ Quality Improvements (Complete)

Future Development Priorities

Next Phase: Core Inventory Features

  1. Items: Primary inventory management with metadata and media
  2. Partners: Institution relationship management
  3. Collections: Grouping and organization features
  4. Tags: Advanced metadata and categorization

Long-Term Enhancements

  1. Accessibility: ARIA labels and enhanced keyboard navigation
  2. Internationalization: Multi-language support integration
  3. Advanced Search: Cross-resource search capabilities
  4. Bulk Operations: Multi-select actions across all resources

Generated on: July 23, 2025
Branch: feature/migrate-to-external-api-client
API Client Version: @metanull/inventory-app-api-client@1.1.19-dev.715.1753