diff --git a/CLAUDE.md b/CLAUDE.md
index f31beed..266b567 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,10 +44,11 @@ This tool addresses the challenge of managing Docker images across numerous GitL
 - Maintain historical data on image usage patterns
 
 ### Vulnerability Management
-- Periodic vulnerability scanning (configurable schedule)
-- Severity classification and reporting
-- Integration with vulnerability databases
-- Automated alerting for critical vulnerabilities
+- Real-time vulnerability scanning with Trivy integration
+- Vulnerability-to-scan job traceability for complete audit trail
+- Severity classification and reporting (Critical, High, Medium, Low, Unspecified)
+- Integration with vulnerability databases (NVD API fallback)
+- WebSocket-based real-time scan status notifications
 
 ### Ignore System
 - **Image-level ignoring**: Exclude specific Docker images from scanning
@@ -81,6 +82,8 @@ This is a full-stack application with separated backend and frontend:
 - **Backend**: Python 3.12+ with FastAPI, SQLite database, and python-gitlab
 - **Frontend**: React 19 + TypeScript + Vite + React Router + Tailwind CSS + shadcn/ui
 - **Database**: SQLite for local storage of image inventory, scan results, and configuration
+- **Real-time Communication**: WebSocket integration with Socket.IO for live scan updates
+- **Vulnerability Scanning**: Trivy integration for comprehensive security analysis
 - **Build Tools**: Vite for frontend, Python packaging for backend
 - **Package Management**: uv/pip for Python, Bun for Node.js
 
@@ -118,10 +121,37 @@ bun preview
 
 ## Architecture Considerations
 
-- **Data Models**: Projects, Files, Images, Vulnerabilities, Ignore Rules (SQLite schema)
-- **API Layer**: FastAPI REST endpoints for frontend communication
-- **Scanning Engine**: Background job system for repository scanning
-- **GitLab Integration**: python-gitlab library for repository and branch access
-- **Database**: SQLite with proper indexing for performance
+- **Data Models**: Projects, Files, Images, Vulnerabilities, ScanJobs, FileImageUsage, IgnoreRules (SQLite schema)
+- **API Layer**: FastAPI REST endpoints with WebSocket support for real-time communication
+- **Scanning Engine**: Asynchronous background job system with concurrent scan prevention
+- **GitLab Integration**: python-gitlab library with group-based filtering for large instances
+- **Database**: SQLite with proper indexing and many-to-many relationships for performance
 - **Security**: Secure handling of GitLab tokens and vulnerability data
-- **Scalability**: Design for scanning hundreds of repositories efficiently
\ No newline at end of file
+- **Real-time Updates**: WebSocket notifications with persistent connections across page navigation
+- **Scalability**: Design for scanning hundreds of repositories efficiently with group filtering
+
+## Key Features Implemented
+
+### Real-time Scan Management
+- **Asynchronous scanning**: Non-blocking scans that allow app usage during execution
+- **Concurrent scan prevention**: Only one scan can run at a time to prevent resource conflicts
+- **WebSocket notifications**: Real-time updates with toast notifications using Sonner
+- **Persistent connection**: WebSocket connection maintained across all pages
+- **Existing scan detection**: New users immediately see ongoing scan status
+
+### Database Schema
+- **Many-to-many relationships**: FileImageUsage table linking files and images
+- **Scan job traceability**: Vulnerabilities linked to the scan job that detected them
+- **Full project paths**: Projects include complete GitLab path (e.g., utils/services/checkmk)
+- **Audit trail**: Complete tracking of when and how vulnerabilities were discovered
+
+### Group-based Filtering
+- **Environment variable**: `GITLAB_GROUPS` for limiting scans to specific groups
+- **Large instance support**: Essential for GitLab instances with hundreds of projects
+- **Development-friendly**: Allows focusing on relevant projects during development
+
+### User Interface
+- **Real-time status indicators**: Connection status and running scan indicators in sidebar
+- **Toast notifications**: Bottom-right positioned for better UX
+- **Responsive design**: Works across different screen sizes with proper layout
+- **Event-driven updates**: Scan jobs page refreshes only when scan events occur
\ No newline at end of file