Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
290 lines (246 loc) · 9.76 KB

ARCHITECTURE.md

File metadata and controls

290 lines (246 loc) · 9.76 KB

BookScan - Project Architecture

📁 Project Structure

bookScan/
│
├── 📄 index.html              # Main HTML entry point
├── 🎨 styles.css              # Mobile-first CSS styling
│
├── 📦 Package Files
│   ├── package.json           # Dependencies & scripts
│   ├── tsconfig.json          # TypeScript configuration
│   └── .gitignore             # Git ignore rules
│
├── 📚 Documentation
│   ├── README.md              # Full project documentation
│   ├── QUICKSTART.md          # Quick start guide
│   └── TODO.md                # Remaining tasks & enhancements
│
├── 💻 Source Code (src/)
│   ├── app.ts                 # Main application logic & UI coordination
│   ├── types.ts               # TypeScript interfaces (Book, Collection)
│   ├── storage.ts             # localStorage management service
│   ├── scanner.ts             # Barcode scanning service (Html5Qrcode)
│   ├── booksAPI.ts            # Google Books API integration
│   └── utils.ts               # UI utilities (toasts, modals, loading)
│
└── 🔨 Build Output (dist/)
    └── [Compiled .js files]   # Generated by TypeScript compiler

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                     USER INTERFACE                       │
│                      (index.html)                        │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ Collections  │  │  Collection  │  │   Scanner    │ │
│  │     View     │  │  Detail View │  │     View     │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│                   APPLICATION LAYER                      │
│                       (app.ts)                           │
│                                                          │
│  • Event handling & user interactions                   │
│  • View switching & navigation                          │
│  • Coordinating services                                │
│  • UI state management                                  │
└─────────────────────────────────────────────────────────┘
                            │
            ┌───────────────┼───────────────┐
            ▼               ▼               ▼
┌──────────────────┐ ┌─────────────┐ ┌────────────────┐
│  StorageService  │ │ ScannerSvc  │ │ BooksAPIService│
│   (storage.ts)   │ │(scanner.ts) │ │ (booksAPI.ts)  │
├──────────────────┤ ├─────────────┤ ├────────────────┤
│ • CRUD           │ │ • Camera    │ │ • Fetch by ISBN│
│   operations     │ │   access    │ │ • Search books │
│ • Collections    │ │ • Barcode   │ │ • Parse API    │
│ • Books          │ │   scanning  │ │   responses    │
│ • localStorage   │ │ • ISBN      │ │                │
│   persistence    │ │   validation│ │                │
└──────────────────┘ └─────────────┘ └────────────────┘
        │                   │                  │
        ▼                   ▼                  ▼
┌──────────────────┐ ┌─────────────┐ ┌────────────────┐
│   localStorage   │ │Html5Qrcode  │ │ Google Books   │
│   (Browser API)  │ │  Library    │ │      API       │
└──────────────────┘ └─────────────┘ └────────────────┘

🔄 Data Flow

Adding a Book via Scan

1. User clicks "Scan Book"
         │
         ▼
2. ScannerService.startScanner()
         │
         ▼
3. Camera opens, user points at barcode
         │
         ▼
4. Html5Qrcode detects ISBN
         │
         ▼
5. BooksAPIService.fetchBookByISBN(isbn)
         │
         ▼
6. Google Books API returns book data
         │
         ▼
7. StorageService.addBookToCollection()
         │
         ▼
8. Data saved to localStorage
         │
         ▼
9. UI refreshed with new book

Loading Collections

1. App initializes
         │
         ▼
2. StorageService.loadCollections()
         │
         ▼
3. Data retrieved from localStorage
         │
         ▼
4. Collections rendered in UI
         │
         ▼
5. User clicks collection
         │
         ▼
6. Books displayed for that collection

🎨 Component Breakdown

Main Views (index.html)

  1. Collections View - Grid of collection cards
  2. Collection Detail View - List of books in a collection
  3. Scanner View - Camera feed for barcode scanning

Modals

  1. New Collection Modal - Input for collection name
  2. Add Book Modal - Manual book entry form
  3. Collection Menu Modal - Rename/Delete options

Shared Components

  • Toast Notifications - Temporary feedback messages
  • Loading Overlay - Spinner for async operations
  • App Header - Title and settings button

🔌 Service APIs

StorageService

loadCollections(): Collection[]
saveCollections(collections: Collection[]): void
createCollection(name: string): Collection
updateCollection(id: string, updates: Partial<Collection>): void
deleteCollection(id: string): void
getCollection(id: string): Collection | null
addBookToCollection(collectionId: string, book: Omit<Book, 'id' | 'addedDate'>): Book
removeBookFromCollection(collectionId: string, bookId: string): void

BooksAPIService

fetchBookByISBN(isbn: string): Promise<Book | null>
searchBooks(query: string): Promise<Book[]>

ScannerService

startScanner(elementId: string, onSuccess: callback, onError?: callback): Promise<void>
stopScanner(): Promise<void>
isRunning(): boolean

UIUtils

showToast(message: string, duration?: number): void
showLoading(message?: string): void
hideLoading(): void
showModal(modalId: string): void
hideModal(modalId: string): void
switchView(viewId: string): void
formatDate(dateString: string): string
escapeHtml(text: string): string

📊 Data Models

Collection

{
    id: string              // Unique identifier
    name: string            // Collection name
    books: Book[]           // Array of books
    createdDate: string     // ISO 8601 date
    modifiedDate: string    // ISO 8601 date
}

Book

{
    id: string              // Unique identifier
    isbn?: string           // ISBN-10 or ISBN-13
    title: string           // Book title
    authors?: string[]      // Array of author names
    publisher?: string      // Publisher name
    publishedDate?: string  // Publication date
    description?: string    // Book description
    thumbnail?: string      // Cover image URL
    addedDate: string       // ISO 8601 date
}

🎯 Design Principles

Mobile-First

  • Touch-friendly targets (48px minimum)
  • Responsive grid layouts
  • Large, clear buttons
  • Optimized for one-handed use

Progressive Enhancement

  • Works without JavaScript (basic HTML)
  • Graceful degradation for older browsers
  • Fallback to manual entry if scanning fails

Performance

  • Minimal dependencies
  • Local-first data storage
  • Lazy loading of book images
  • Efficient DOM updates

Accessibility

  • Semantic HTML
  • ARIA labels for icons
  • Keyboard navigation support
  • High contrast ratios

🔐 Security Considerations

  • XSS Prevention via UIUtils.escapeHtml()
  • No sensitive data stored
  • HTTPS required for camera access
  • No backend = no server-side vulnerabilities

🚀 Build Process

Source TypeScript (.ts)
        │
        ▼
TypeScript Compiler (tsc)
        │
        ▼
JavaScript (.js) + Source Maps (.js.map)
        │
        ▼
Type Declarations (.d.ts)
        │
        ▼
Output to dist/ folder
        │
        ▼
index.html loads from dist/

📈 Future Architecture Considerations

When implementing planned features:

  • Export/Import: Add ExportService for JSON/CSV handling
  • Search: Add SearchService with indexing
  • PWA: Add ServiceWorker and manifest.json
  • Sync: Consider SyncService for cloud backup
  • Analytics: Optional AnalyticsService wrapper
  • Testing: Jest for unit tests, Playwright for E2E

This architecture prioritizes simplicity, maintainability, and mobile performance while remaining extensible for future enhancements.