# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a GitLab Docker Images Tracker project designed to monitor, track, and manage Docker images across multiple GitLab repositories with automated vulnerability scanning and lifecycle management.

## Project Purpose

This tool addresses the challenge of managing Docker images across numerous GitLab projects by:

1. **Discovery & Tracking**: Automatically discovers Docker images referenced in:
   - `docker-compose*.yml` files
   - `Dockerfile*` files  
   - `.gitlab-ci*.yml` files
   - Across main branches (main, master, develop)

2. **Lifecycle Management**: Tracks image usage over time to identify:
   - Images currently in use across projects
   - Images that have been removed from files, branches, or projects
   - Images that are no longer referenced anywhere

3. **Vulnerability Scanning**: Provides periodic vulnerability scanning (configurable intervals) with severity classification:
   - Critical vulnerabilities
   - High severity vulnerabilities
   - Medium severity vulnerabilities
   - Low severity vulnerabilities
   - Unspecified severity vulnerabilities

4. **Ignore Management**: Offers granular control to exclude from scanning:
   - Specific Docker images
   - Entire files (ignoring all images within)
   - Entire projects (ignoring all files and images within)

5. **Reporting**: Generates actionable reports showing which images need updates and where they are being used across the GitLab infrastructure.

## Core Features

### Image Discovery
- Scan GitLab repositories for Docker images in configuration files
- Parse `docker-compose*.yml`, `Dockerfile*`, and `.gitlab-ci*.yml` files
- Track images across main branches (main, master, develop)
- 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

### Ignore System
- **Image-level ignoring**: Exclude specific Docker images from scanning
- **File-level ignoring**: Exclude entire files from image discovery
- **Project-level ignoring**: Exclude entire projects from scanning
- Maintain ignore lists with reasoning and timestamps

### Reporting & Analytics
- Current image inventory across all projects
- Vulnerability status dashboard
- Image lifecycle tracking (active, deprecated, removed)
- Project-specific image usage reports

## Project Structure

This is a full-stack application with separated backend and frontend:

```
├── backend/          # Python backend with FastAPI
│   ├── main.py       # FastAPI application entry point
│   ├── pyproject.toml # Python dependencies and configuration
│   └── README.md     # Backend documentation
└── frontend/         # React + TypeScript frontend
    ├── src/          # React components and application code
    ├── package.json  # Node.js dependencies and scripts
    └── vite.config.ts # Vite build configuration
```

## Technology Stack

- **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
- **Build Tools**: Vite for frontend, Python packaging for backend
- **Package Management**: uv/pip for Python, Bun for Node.js

## Commands

### Backend Commands
```bash
cd backend
# Install dependencies
uv sync
# Run tests
uv run pytest
# Format code
uv run black .
# Lint code
uv run ruff check .
# Run development server (runs on port 5000)
uv run python main.py
```

### Frontend Commands
```bash
cd frontend
# Install dependencies
bun install
# Start development server (runs on port 3000)
bun dev
# Build for production
bun build
# Lint code
bun lint
# Preview production build
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
- **Security**: Secure handling of GitLab tokens and vulnerability data
- **Scalability**: Design for scanning hundreds of repositories efficiently