159 lines
No EOL
5.1 KiB
Markdown
159 lines
No EOL
5.1 KiB
Markdown
# 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 |