agent_tracker/CLAUDE.md

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

uvicorn main:app --reload --port 8000

Access at: http://localhost:8000

Installing Dependencies

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