⚠️ PORTFOLIO DEMONSTRATION PROJECT ONLY
This is a showcase application with demo data. NOT FOR PRODUCTION USE WITH REAL ASSETS.

VitalLock is a digital asset inheritance system that monitors user activity and transfers digital assets to designated beneficiaries after extended inactivity.

VitalLock helps manage digital asset inheritance. When crypto holders become inactive, their assets can be transferred to designated beneficiaries.

• 🔄 Activity Monitoring - Tracks user interactions across web, CLI, and API
• 🔐 Encryption - AES-256-GCM for private key storage
• 👥 Beneficiary Management - Designate asset inheritors
• ⏰ Configurable Thresholds - Inactivity periods (7-365 days)
• 🎭 Demo Mode - Test with fake data
• 📱 Responsive Design - Works on all devices
• 🚀 Real-time Updates - Live activity monitoring

graph TB
    subgraph "Frontend Layer"
        A[React SPA] --> B[Authentication Context]
        A --> C[Demo Mode Service]
        A --> D[API Client]
    end
    
    subgraph "Backend Layer"
        E[Express.js API] --> F[Authentication Middleware]
        E --> G[Encryption Service]
        E --> H[Activity Monitoring]
    end
    
    subgraph "Data Layer"
        I[PostgreSQL Database] --> J[Users & Auth]
        I --> K[Encrypted Assets]
        I --> L[Beneficiaries]
        I --> M[Activity History]
        N[Redis Cache] --> O[Session Data]
        N --> P[Activity Status]
    end
    
    subgraph "CLI Tool"
        Q[Commander.js CLI] --> R[Heartbeat Service]
        Q --> S[Asset Management]
    end
    
    D --> E
    R --> E
    E --> I
    E --> N
    
    style A fill:#8b5cf6
    style E fill:#10b981
    style I fill:#3b82f6
    style Q fill:#f59e0b

1. Presentation Layer (React Frontend)

   • Modern SPA with TypeScript and Tailwind CSS
   • Context-based state management
   • Demo mode with realistic fake data
   • Responsive design with smooth animations

2. Application Layer (Node.js Backend)

   • RESTful API with Express.js
   • JWT-based authentication
   • AES-256-GCM encryption service
   • Activity monitoring and risk assessment

3. Data Layer (PostgreSQL + Redis)

   • Relational database for persistent storage
   • Redis for session and activity caching
   • Encrypted storage for sensitive data

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant B as Backend
    participant E as Encryption Service
    participant D as Database
    
    U->>F: Submit Private Key
    F->>B: Encrypted Request (HTTPS)
    B->>E: Encrypt with AES-256-GCM
    E->>E: Generate IV + Auth Tag
    E->>B: Return Encrypted Object
    B->>D: Store {iv, encryptedData, authTag}
    D-->>B: Confirmation
    B-->>F: Success Response
    F-->>U: Asset Secured

• Zero-Knowledge: Server never sees plaintext private keys
• AES-256-GCM: Symmetric encryption
• Random IVs: Fresh initialization vector per encryption
• Auth Tags: Tamper detection
• JWT Authentication: Stateless token-based session management
• HTTPS Only: All communications encrypted in transit

VitalLock includes a comprehensive demo mode for portfolio demonstration:

• Realistic Data: $110,150+ in fake cryptocurrency assets
• Activity Simulation: Automated heartbeats and status updates
• Full Functionality: All features work with fake data
• Visual Indicators: Clear "Demo Mode" banners throughout
• Safe Testing: No real API calls or data storage

• 5 diverse cryptocurrency assets (Bitcoin, Ethereum, DeFi, NFTs)
• 4 beneficiaries with different relationships
• Historical activity data spanning months
• Realistic asset values and portfolio statistics

• Node.js 18+ and npm
• PostgreSQL 14+
• Redis (optional, graceful fallback)

# Clone the repository
git clone <repository-url>
cd vital-lock

# Install dependencies for all components
npm run setup

# Configure environment variables
cp .env.example .env
# Edit .env with your configuration

# Set up database
npm run db:migrate
npm run db:seed

# Start development servers
npm run dev

# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=vitalsign_dev
DB_USER=your_user
DB_PASSWORD=your_password

# Security Keys (MUST be exactly 32 characters)
ENCRYPTION_KEY=your-32-character-secret-key-here
JWT_SECRET=your-jwt-secret-key

# Optional Services
REDIS_URL=redis://localhost:6379
SMTP_HOST=your-smtp-host
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password

• React 18 - Modern UI library with hooks
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework
• React Router - Client-side routing
• Axios - HTTP client with interceptors
• React Hot Toast - Elegant notifications

• Node.js - JavaScript runtime
• Express.js - Web application framework
• TypeScript - Type-safe server development
• PostgreSQL - Relational database
• Redis - In-memory data store
• JWT - JSON Web Tokens for auth
• express-validator - Input validation

• Commander.js - Command-line interface framework
• Chalk - Terminal string styling
• Inquirer.js - Interactive command prompts

vital-lock/
├── frontend/                 # React frontend application
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   ├── pages/          # Main application pages
│   │   ├── contexts/       # React contexts (Auth, etc.)
│   │   ├── utils/          # Utilities and helpers
│   │   └── types/          # TypeScript type definitions
│   └── public/             # Static assets
├── backend/                  # Node.js API server
│   ├── routes/             # API route handlers
│   ├── models/             # Database models
│   ├── middleware/         # Express middleware
│   ├── utils/              # Server utilities
│   └── migrations/         # Database migrations
├── cli/                      # Command-line interface
│   ├── commands/           # CLI command implementations
│   ├── utils/              # CLI utilities
│   └── config/             # CLI configuration
└── docs/                     # Additional documentation

npm run setup              # Install all dependencies
npm run dev               # Start frontend and backend
npm run build             # Build for production
npm run test              # Run all tests
npm run lint              # Lint all code

npm run frontend          # Start React dev server
npm run build:frontend    # Build React for production
npm run test:frontend     # Run React tests

npm run backend           # Start Express server
npm run build:backend     # Build backend TypeScript
npm run test:backend      # Run backend tests
npm run db:migrate        # Run database migrations
npm run db:seed           # Seed database with test data

npm run cli               # Start CLI in development
vitalsign --help          # Show CLI help (after global install)

POST /api/auth/login      # User login
POST /api/auth/register   # User registration
POST /api/auth/verify     # Token verification

GET    /api/assets        # List user assets
POST   /api/assets        # Create new asset
PUT    /api/assets/:id    # Update asset
DELETE /api/assets/:id    # Delete asset

GET  /api/activity/status   # Current activity status
POST /api/activity/heartbeat # Record activity
GET  /api/activity/history  # Activity history

GET    /api/legacy/beneficiaries     # List beneficiaries
POST   /api/legacy/beneficiaries     # Add beneficiary
PUT    /api/legacy/beneficiaries/:id # Update beneficiary
DELETE /api/legacy/beneficiaries/:id # Remove beneficiary

• Dark Theme: Modern dark UI optimized for crypto users
• Responsive Layout: Mobile-first design approach
• Smooth Animations: CSS transitions and keyframe animations
• Loading States: Skeleton screens and loading indicators
• Color-Coded Status: Visual feedback for different states

• Animated Landing Page: Engaging hero section with feature showcase
• Demo Mode Toggle: Easy switching between demo and real modes
• Real-time Updates: Live activity monitoring
• Form Validation: Comprehensive client-side validation
• Modal Interactions: Smooth modal experiences with proper UX

• Unit Tests: Component and utility function testing
• Integration Tests: API endpoint testing
• E2E Tests: Full user journey testing
• Security Tests: Encryption and authentication testing

# Run all tests
npm run test

# Run specific test suites
npm run test:frontend
npm run test:backend
npm run test:cli

# Run tests with coverage
npm run test:coverage

# Build all components for production
npm run build

# Environment setup for production
export NODE_ENV=production
export ENCRYPTION_KEY=your-production-key
export JWT_SECRET=your-production-jwt-secret

# Build Docker images
docker-compose build

# Start production stack
docker-compose up -d

This is a portfolio demonstration project. For educational purposes, you can:

1. Fork the repository
2. Create a feature branch
3. Make improvements or add features
4. Submit a pull request

This project is for portfolio demonstration purposes. See SECURITY.md for important security considerations.

• DEMO ONLY: This application is for demonstration purposes
• NOT PRODUCTION READY: Do not use with real cryptocurrency
• EDUCATIONAL PROJECT: Designed to showcase development skills
• SECURITY LIMITATIONS: See SECURITY.md for detailed limitations

For questions about this portfolio project, please reach out through:

• GitHub Issues for technical questions
• LinkedIn for professional inquiries
• Email for collaboration opportunities

Built with ❤️ as a portfolio demonstration of modern full-stack development capabilities.