Architecture Overview

Pack-Man is built with a modern, scalable architecture designed for performance, maintainability, and extensibility.

Technology Stack

Core Framework

Next.js 16 - React framework with App Router for server-side rendering and API routes
TypeScript 5 - Type-safe development with strict configuration
React 19 - Latest React with concurrent features and improved performance

Styling & UI

Tailwind CSS 4 - Utility-first CSS with CSS variables for theming
shadcn/ui - High-quality components built on Radix UI primitives
Lucide React - Consistent icon library
next-themes - Seamless dark/light mode support

State & Data Management

React Hook Form - Performant form handling with validation
Axios - HTTP client with interceptors and error handling
p-limit - Concurrency control for parallel API requests

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Client Layer                          │
├─────────────────────────────────────────────────────────────┤
│  Web App  │  Chrome Extension  │  VS Code Extension (Planned)│
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                     Next.js App Router                       │
├─────────────────────────────────────────────────────────────┤
│  Pages  │  API Routes  │  Components  │  Hooks  │  Utils    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Service Layer                             │
├─────────────────────────────────────────────────────────────┤
│  GitHub Service  │  Package Services  │  Cache Service      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   External APIs                              │
├─────────────────────────────────────────────────────────────┤
│  GitHub API  │  npm Registry  │  PyPI  │  pub.dev           │
└─────────────────────────────────────────────────────────────┘

Core Components

1. Parser System

Strategy pattern implementation for parsing different dependency file formats:

interface DependencyParser {
  parse(content: string): ParsedDependencies;
  validate(content: string): boolean;
}

// Implementations
- PackageJsonParser (npm)
- RequirementsTxtParser (pip)
- PubspecYamlParser (pub)

Features:

Automatic file type detection
Robust error handling
Support for multiple dependency sections
Version constraint parsing

2. GitHub Integration

Comprehensive GitHub API integration with token management:

class GitHubService {
  - validateRepository()
  - searchDependencyFiles()
  - downloadFileContent()
  - validateToken()
  - getRateLimit()
}

Features:

Token-based authentication
Rate limit management
Private repository support
Automatic file discovery
Error recovery and retry logic

3. Package Analysis Engine

Parallel package version checking with concurrency control:

async function analyzePackages(packages: Package[]) {
  const limit = pLimit(10); // Max 10 concurrent requests
  
  const results = await Promise.all(
    packages.map(pkg => 
      limit(() => checkPackageVersion(pkg))
    )
  );
  
  return results;
}

Features:

Concurrent API requests (10 parallel)
Registry-specific adapters (npm, PyPI, pub.dev)
Version comparison with semver
Comprehensive error handling
Progress tracking

4. Cache System

Multi-layer caching strategy for performance:

interface CacheService {
  successCache: Map<string, CachedResult>; // 5 min TTL
  errorCache: Map<string, CachedError>;    // 2 min TTL
  
  get(key: string): CachedResult | null;
  set(key: string, value: any, ttl: number): void;
  clear(): void;
}

Features:

Separate success and error caches
Configurable TTL per cache type
Automatic cleanup of expired entries
Size limiting (max 100 entries)
Cache invalidation on API changes

Data Flow

1. File Upload Flow

User uploads file
    ↓
File detection (MIME type, extension, content)
    ↓
Parser selection (npm/pip/pub)
    ↓
Dependency extraction
    ↓
Parallel version checking
    ↓
Results aggregation
    ↓
UI update with statistics

2. GitHub URL Flow

User enters GitHub URL
    ↓
URL validation (real-time)
    ↓
Repository validation (GitHub API)
    ↓
Dependency file discovery
    ↓
File selection by user
    ↓
File download (raw content)
    ↓
Standard analysis flow

3. Chrome Extension Flow

User visits GitHub page
    ↓
Content script detects repository
    ↓
Background worker checks cache
    ↓
API request (if not cached)
    ↓
Badge injection into page
    ↓
Cache result (5 min success, 2 min error)

API Architecture

Endpoints

POST /api/analyze-packages

Accepts file content and filename
Returns package analysis results
Handles all supported formats

GET /api/health

Health check endpoint
Returns service status

Request/Response Flow

// Request
{
  content: string;      // File content
  fileName?: string;    // Optional filename for detection
}

// Response
{
  packages: PackageInfo[];
  summary: AnalysisSummary;
}