# CLAUDE.md

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

## Project Overview

AgentHub is a FastAPI-based AI Agent Management System with MongoDB backend. It provides role-based authentication (admin/user), agent CRUD operations, user management, and a web interface built with Jinja2 templates and Bootstrap 5.

## Common Development Tasks

### Running the Application
```bash
uvicorn main:app --reload --port 8000
```
Access at: http://localhost:8000

### Installing Dependencies
```bash
pip install -r requirements.txt
```

### Environment Setup
Create `.env` file with:
- `MONGODB_URI`: MongoDB connection string (default: mongodb://localhost:27017)
- `MONGODB_DBNAME`: Database name (default: agenthub_db)
- `SECRET_KEY`: JWT secret key
- `ALGORITHM`: JWT algorithm (default: HS256)
- `ACCESS_TOKEN_EXPIRE_MINUTES`: Token expiration (default: 60)

### Default Login Credentials
- Admin: `admin@agenthub.com` / `admin123`
- Test User: `test@example.com` / `testpass123`

## Code Architecture

### Core Application Structure

**main.py**: FastAPI application with:
- JWT cookie-based authentication system
- HTML routes for web interface
- REST API endpoints for agent/user management
- Role-based access control (admin vs regular user)
- Template rendering with Jinja2

**Key Authentication Functions**:
- `get_current_user_optional()`: Cookie-based auth for templates
- `get_current_user_from_cookie()`: Required auth for API endpoints
- `require_admin()`: Admin-only access control

### Data Layer

**models.py**: Pydantic models for:
- `AiAgent`: Core agent model with comprehensive fields
- `UserCreate/UserResponse`: User management models
- `AiAgentCreate/AiAgentResponse`: API request/response models

**crud.py**: Database operations using Motor (async MongoDB driver):
- User CRUD: authentication, creation, management
- Agent CRUD: create, read, update, delete with user ownership
- Advanced features: search, filtering, statistics, pagination
- All operations use ObjectId for MongoDB document IDs

**database.py**: MongoDB connection setup with Motor async client

**auth.py**: JWT authentication with:
- bcrypt password hashing
- JWT token creation/validation using python-jose
- Configurable token expiration

### Frontend Templates

Located in `templates/` directory:
- **base.html**: Bootstrap 5 base template with navigation
- **nav.html**: Dynamic navigation based on user role
- **index.html**: Landing page
- **login.html/register.html**: Authentication forms
- **agent_register.html**: Agent creation form
- **agent_management.html**: Agent dashboard with real data
- **search.html**: Global search functionality
- **user_management.html**: User management interface
- **admin/dashboard.html**: Admin statistics and management

### Static Assets

**static/style.css**: Custom CSS with:
- CSS variables for consistent theming
- Gradient backgrounds and modern styling
- Responsive design for mobile devices
- Bootstrap 5 customizations

## Key Features

### Authentication Flow
- Cookie-based JWT authentication
- Role-based access (admin/user permissions)
- Automatic redirects based on user role
- Secure logout with token cleanup

### Agent Management
- Full CRUD operations with user ownership
- Status tracking (Active, Inactive, Development, Deprecated)
- Rich metadata: tags, userbase, department, contact person
- Search functionality across multiple fields
- Admin can view/manage all agents

### User Management
- User registration with validation
- Admin user creation capabilities
- Profile management
- User statistics and administration

### Database Integration
- MongoDB with proper ObjectId handling
- Async operations using Motor driver
- Indexed queries for performance
- Data aggregation for statistics

## Development Guidelines

### Database Operations
- Always use ObjectId for MongoDB document IDs
- Use Motor async driver methods (await collection.find_one())
- Handle ObjectId conversion in CRUD operations
- Implement proper error handling with try/except blocks

### Authentication
- Use cookie-based auth for web interface
- API endpoints require `get_current_user_from_cookie()` dependency
- Admin endpoints use `require_admin()` dependency
- Always validate user permissions for data access

### Template Context
- Pass `current_user` to all templates for navigation
- Handle dict objects (not User model instances) in templates
- Use proper null checks for optional user data

### API Response Models
- Convert ObjectId to string in API responses
- Handle optional datetime fields with isoformat()
- Maintain consistency between Create and Response models

### Error Handling
- Provide meaningful error messages in templates
- Use proper HTTP status codes in API responses
- Graceful degradation for missing data

## Project Dependencies

Key dependencies from requirements.txt:
- **fastapi**: Web framework
- **uvicorn**: ASGI server
- **motor**: Async MongoDB driver
- **pymongo**: MongoDB operations
- **python-jose**: JWT token handling
- **passlib**: Password hashing
- **bcrypt**: Password encryption
- **pydantic**: Data validation
- **jinja2**: Template engine
- **python-multipart**: Form handling