# AI Platform Admin Portal

**Repository Path**: albatross_llm/ai-platform-admin

## Basic Information

- **Project Name**: AI Platform Admin Portal
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-30
- **Last Updated**: 2025-11-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Platform Admin System

A comprehensive admin platform for managing AI agents, built with **ASP.NET Core** (backend) and **React + Ant Design Pro** (frontend).

## Features

### 1. User Management
- Create, edit, and view users
- Three-tier role system:
  - **AppUser**: Can only login to ChatApp (not this admin system)
  - **PlatformUser**: Can login to admin system, create teams/KBs/VEs, manage own profile
  - **Administrator**: Full system access
- Only administrators can create/edit/delete users
- Users can update their own profile and change password

### 2. Team Management
- Create, edit, and view teams
- Assign multiple users to teams
- Designate multiple team administrators
- Team admins can:
  - View/edit team information
  - Delete teams
  - Manage team members
  - Assign new team administrators
- Platform users can create teams

### 3. Knowledge Base Management
- Create, edit, and view knowledge bases
- Upload multiple documents per knowledge base
- Set team access permissions or make public (all-user visible)
- Designate multiple KB administrators
- KB admins can:
  - View/edit/delete knowledge bases
  - Manage documents
  - Control team access permissions
  - Assign new KB administrators
- Platform users can create knowledge bases

### 4. Virtual Expert Management
- Create and configure custom ChatBot settings
- Configure:
  - System meta prompts
  - Model versions
  - Accessible knowledge bases
  - Available plugins
- Set team access permissions or make public
- Designate multiple VE administrators
- VE admins can:
  - View/edit/delete virtual experts
  - Assign new VE administrators
- Platform users can create virtual experts

### 5. Token Usage Tracking
- Monitor LLM token consumption per user
- View usage analytics and cost tracking
- Filter by user, virtual expert, and date range

## 🔐 Security

**IMPORTANT**: This project follows security best practices for credential management.

- **Environment Variables**: All sensitive data (passwords, JWT keys) should be provided via environment variables
- **No Hardcoded Secrets**: Configuration files do not contain plaintext passwords
- **Production Ready**: Supports Docker Secrets and cloud key management services

📖 **See [SECURITY.md](SECURITY.md) for detailed security configuration guide**

Quick setup:
```bash
# 1. Copy environment template
cp env.example .env

# 2. Set strong passwords in .env
nano .env

# 3. Never commit .env to Git!
```

## Tech Stack

### Backend
- **Framework**: ASP.NET Core 8.0
- **Database**: PostgreSQL
- **ORM**: Entity Framework Core
- **Authentication**: JWT Bearer
- **API Documentation**: Swagger/OpenAPI
- **Password Hashing**: BCrypt

### Frontend
- **Framework**: React 18 with TypeScript
- **UI Library**: Ant Design + Ant Design Pro Components
- **Routing**: React Router v6
- **HTTP Client**: Axios
- **State Management**: React Context API
- **Internationalization**: i18next

### DevOps
- **Containerization**: Docker & Docker Compose
- **Database**: PostgreSQL 16
- **Web Server**: Nginx (for frontend)
- **Security**: Environment-based configuration

## Project Structure

```
ai-platform-admin/
├── backend/                    # ASP.NET Core API
│   ├── Controllers/           # API endpoints
│   ├── Data/                  # DbContext
│   ├── Models/                # Entity models
│   ├── Migrations/            # EF Core migrations
│   ├── Program.cs             # App configuration
│   ├── appsettings.json       # Configuration
│   └── Dockerfile             # Backend Docker image
├── frontend/                   # React frontend
│   ├── src/
│   │   ├── components/        # Reusable components
│   │   ├── contexts/          # React contexts
│   │   ├── pages/             # Page components
│   │   ├── services/          # API services
│   │   ├── types/             # TypeScript types
│   │   └── App.tsx            # Main app component
│   ├── public/                # Static assets
│   ├── nginx.conf             # Nginx configuration
│   └── Dockerfile             # Frontend Docker image
├── docker-compose.yml          # Multi-container setup
├── DOCKER.md                   # Docker documentation
└── README.md                   # This file
```

## Getting Started

### Option 1: Docker (Recommended)

1. **Prerequisites**:
   - Docker and Docker Compose installed
   - Ports 80, 5000, and 5432 available

2. **Start all services**:
   ```bash
   docker-compose up -d
   ```

3. **Access the application**:
   - Frontend: http://localhost
   - Backend API: http://localhost:5000
   - Swagger UI: http://localhost:5000/swagger

4. **Create first administrator** (see DOCKER.md for details)

### Option 2: Local Development

#### Backend Setup

1. **Prerequisites**:
   - .NET 8 SDK
   - PostgreSQL 16

2. **Install dependencies**:
   ```bash
   cd backend
   dotnet restore
   ```

3. **Update connection string** in `appsettings.json`:
   ```json
   {
     "ConnectionStrings": {
       "DefaultConnection": "Host=localhost;Database=aiplatform;Username=postgres;Password=yourpassword"
     }
   }
   ```

4. **Create database and run migrations**:
   ```bash
   dotnet ef database update
   ```

5. **Run the backend**:
   ```bash
   dotnet run
   ```

#### Frontend Setup

1. **Prerequisites**:
   - Node.js 18+
   - npm or yarn

2. **Install dependencies**:
   ```bash
   cd frontend
   npm install --legacy-peer-deps
   ```

3. **Update API URL** in `src/services/api.ts` if needed

4. **Run the frontend**:
   ```bash
   npm start
   ```

5. **Access**: http://localhost:3000

## API Documentation

### Authentication Endpoints

- `POST /api/Auth/register` - Register new user (creates AppUser by default)
- `POST /api/Auth/login` - Login (PlatformUser and Administrator only)
- `GET /api/Auth/me` - Get current user info
- `PUT /api/Auth/change-password` - Change own password
- `PUT /api/Auth/profile` - Update own profile

### User Management (Admin only)

- `GET /api/Users` - List all users
- `GET /api/Users/{id}` - Get user by ID
- `POST /api/Users` - Create user
- `PUT /api/Users/{id}` - Update user
- `DELETE /api/Users/{id}` - Delete user

### Team Management

- `GET /api/Teams` - List all teams
- `POST /api/Teams` - Create team
- `PUT /api/Teams/{id}` - Update team (team admin or platform admin)
- `DELETE /api/Teams/{id}` - Delete team (team admin or platform admin)
- `POST /api/Teams/{teamId}/users/{userId}` - Add user to team
- `DELETE /api/Teams/{teamId}/users/{userId}` - Remove user from team
- `POST /api/Teams/{teamId}/admins/{userId}` - Add team admin
- `DELETE /api/Teams/{teamId}/admins/{userId}` - Remove team admin

### Knowledge Base Management

- `GET /api/KnowledgeBases` - List accessible KBs
- `POST /api/KnowledgeBases` - Create KB
- `PUT /api/KnowledgeBases/{id}` - Update KB (KB admin only)
- `DELETE /api/KnowledgeBases/{id}` - Delete KB (KB admin only)
- `GET /api/KnowledgeBases/{id}/documents` - List documents
- `POST /api/KnowledgeBases/{id}/documents` - Upload document
- `DELETE /api/KnowledgeBases/documents/{documentId}` - Delete document
- `POST /api/KnowledgeBases/{id}/admins/{userId}` - Add KB admin
- `POST /api/KnowledgeBases/{id}/teams/{teamId}` - Grant team access

### Virtual Expert Management

- `GET /api/VirtualExperts` - List accessible VEs
- `POST /api/VirtualExperts` - Create VE
- `PUT /api/VirtualExperts/{id}` - Update VE (VE admin only)
- `DELETE /api/VirtualExperts/{id}` - Delete VE (VE admin only)
- `POST /api/VirtualExperts/{id}/admins/{userId}` - Add VE admin
- `POST /api/VirtualExperts/{id}/teams/{teamId}` - Grant team access
- `POST /api/VirtualExperts/{veId}/knowledgebases/{kbId}` - Link KB
- `POST /api/VirtualExperts/{veId}/plugins/{pluginId}` - Link plugin

### Token Usage

- `GET /api/TokenUsage` - List token usage (with filters)
- `POST /api/TokenUsage` - Record token usage
- `GET /api/TokenUsage/users/{userId}/summary` - User summary
- `GET /api/TokenUsage/virtualexperts/{veId}/summary` - VE summary

### Plugins

- `GET /api/Plugins` - List all plugins
- `POST /api/Plugins` - Create plugin
- `PUT /api/Plugins/{id}` - Update plugin
- `DELETE /api/Plugins/{id}` - Delete plugin

## Permission System

### Role Hierarchy

1. **Administrator** (Role = 2)
   - Full access to all features
   - Can create/edit/delete users
   - Can manage all teams, KBs, and VEs

2. **PlatformUser** (Role = 1)
   - Can login to admin system
   - Can create teams, KBs, and VEs
   - Can update own profile
   - Becomes admin of resources they create

3. **AppUser** (Role = 0)
   - Cannot login to admin system
   - Can only login to ChatApp

### Resource-Level Permissions

- **Team Admins**: Manage team info, members, and assign new team admins
- **KB Admins**: Manage KB content, documents, team access, and assign new KB admins
- **VE Admins**: Manage VE configuration and assign new VE admins
- **Public Resources**: KBs and VEs can be marked as public for all-user access
- **Team Access**: Resources can grant access to specific teams

## Database Schema

### Core Tables

- **Users**: User accounts with roles
- **Teams**: User teams/groups
- **UserTeam**: Many-to-many user-team relationship
- **TeamAdmin**: Team administrators
- **KnowledgeBases**: Knowledge base configurations
- **Documents**: Uploaded documents
- **KnowledgeBaseAdmin**: KB administrators
- **KnowledgeBaseTeamAccess**: Team access to KBs
- **VirtualExperts**: ChatBot configurations
- **VirtualExpertAdmin**: VE administrators
- **VirtualExpertTeamAccess**: Team access to VEs
- **VirtualExpertKnowledgeBase**: VE-KB relationships
- **Plugins**: Available plugins
- **VirtualExpertPlugin**: VE-plugin relationships
- **TokenUsage**: LLM token consumption logs

## Security

- **Password Hashing**: BCrypt with salt
- **Authentication**: JWT Bearer tokens
- **Authorization**: Role-based and resource-based access control
- **CORS**: Configured for frontend origin
- **SQL Injection**: Protected by Entity Framework parameterization

## Development

### Backend Development

```bash
cd backend

# Run with hot reload
dotnet watch run

# Run tests (if available)
dotnet test

# Create migration
dotnet ef migrations add MigrationName

# Apply migrations
dotnet ef database update

# Build for production
dotnet publish -c Release
```

### Frontend Development

```bash
cd frontend

# Start dev server
npm start

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint
```

## Production Deployment

See [DOCKER.md](./DOCKER.md) for detailed production deployment instructions, including:

- Security best practices
- Environment variables configuration
- Database backup strategies
- SSL/HTTPS setup
- Monitoring and logging

## Troubleshooting

### Backend won't start
- Check PostgreSQL is running
- Verify connection string in appsettings.json
- Ensure database exists and migrations are applied

### Frontend can't connect to API
- Verify backend is running on http://localhost:5000
- Check CORS settings in backend Program.cs
- Verify API URL in frontend src/services/api.ts

### Database errors
- Check PostgreSQL logs
- Verify user permissions
- Ensure database schema is up to date

## Future Enhancements (From Requirements)

### Multi-Tenant Support
The system is designed to support multi-tenancy with the following structure:
- Add `TenantId` to all entity models
- Implement tenant isolation at data access layer
- Add tenant selection during login
- Filter all queries by current tenant

### Multi-Language (i18n) Support
Frontend is ready for internationalization:
- Install i18next and react-i18next (already added)
- Create language resource files (en.json, zh.json, etc.)
- Wrap strings with `useTranslation()` hook
- Add language switcher in header

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

[Your License Here]

## Support

For issues and questions:
- Create an issue in the repository
- Contact the development team
- Check documentation in CLAUDE.md and DOCKER.md