Timothy
689db5ab33
Beeline - Open-source LLM observability and control platform Features: - Real-time agent monitoring dashboard - LLM metrics and analytics (TimescaleDB) - Cost tracking and budget controls - WebSocket event streaming - MCP (Model Context Protocol) server Apache 2.0 License
223 lines
7.7 KiB
Markdown
223 lines
7.7 KiB
Markdown
# Architecture Overview
|
|
|
|
This document describes the high-level architecture of Beeline.
|
|
|
|
## System Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Client │
|
|
│ (Web Browser) │
|
|
└─────────────────────────┬───────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ Docker Network │
|
|
│ │
|
|
│ ┌─────────────────────┐ ┌─────────────────────────┐ │
|
|
│ │ honeycomb │ │ hive │ │
|
|
│ │ (Frontend) │ ───▶ │ (Backend) │ │
|
|
│ │ │ │ │ │
|
|
│ │ React + Vite │ │ Express + TypeScript │ │
|
|
│ │ Port: 3000 │ │ Port: 4000 │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌───────────────┐ │ │ ┌─────────────────┐ │ │
|
|
│ │ │ Nginx │ │ │ │ Routes │ │ │
|
|
│ │ │ (production) │ │ │ │ /api, /health │ │ │
|
|
│ │ └───────────────┘ │ │ └────────┬────────┘ │ │
|
|
│ └─────────────────────┘ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌─────────────────┐ │ │
|
|
│ │ │ Controllers │ │ │
|
|
│ │ └────────┬────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌─────────────────┐ │ │
|
|
│ │ │ Services │ │ │
|
|
│ │ └────────┬────────┘ │ │
|
|
│ │ │ │ │
|
|
│ └───────────┼─────────────┘ │
|
|
└───────────────────────────────────────────┼────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────┐
|
|
│ Database │
|
|
│ (PostgreSQL/etc) │
|
|
└─────────────────────────┘
|
|
```
|
|
|
|
## Components
|
|
|
|
### Frontend (honeycomb/)
|
|
|
|
The frontend is a single-page application built with:
|
|
|
|
- **React 18** - UI library
|
|
- **TypeScript** - Type safety
|
|
- **Vite** - Build tool and dev server
|
|
- **React Router** - Client-side routing
|
|
|
|
**Key Directories:**
|
|
|
|
| Directory | Purpose |
|
|
|-----------|---------|
|
|
| `src/components/` | Reusable UI components |
|
|
| `src/pages/` | Page-level components (routes) |
|
|
| `src/hooks/` | Custom React hooks |
|
|
| `src/services/` | API client and external services |
|
|
| `src/types/` | TypeScript type definitions |
|
|
| `src/utils/` | Utility functions |
|
|
| `src/styles/` | Global styles and CSS |
|
|
|
|
**Production Build:**
|
|
- Vite builds static assets
|
|
- Nginx serves the built files
|
|
- API requests proxied to backend
|
|
|
|
### Backend (hive/)
|
|
|
|
The backend is a RESTful API built with:
|
|
|
|
- **Express** - Web framework
|
|
- **TypeScript** - Type safety
|
|
- **Zod** - Runtime validation
|
|
- **Helmet** - Security headers
|
|
|
|
**Key Directories:**
|
|
|
|
| Directory | Purpose |
|
|
|-----------|---------|
|
|
| `src/routes/` | API route definitions |
|
|
| `src/controllers/` | Request handlers |
|
|
| `src/services/` | Business logic |
|
|
| `src/middleware/` | Express middleware |
|
|
| `src/models/` | Data models |
|
|
| `src/types/` | TypeScript types |
|
|
| `src/utils/` | Utility functions |
|
|
| `src/config/` | Configuration loading |
|
|
|
|
**API Structure:**
|
|
|
|
```
|
|
GET /health # Health check endpoints
|
|
GET /health/ready # Readiness probe
|
|
GET /health/live # Liveness probe
|
|
|
|
GET /api # API info
|
|
GET /api/users # Example resource
|
|
```
|
|
|
|
## Request Flow
|
|
|
|
1. **Client** makes HTTP request
|
|
2. **Nginx** (production) or **Vite** (dev) receives request
|
|
3. Static assets served directly; API requests proxied
|
|
4. **Express** receives API request
|
|
5. **Middleware** processes (auth, logging, validation)
|
|
6. **Router** matches route to controller
|
|
7. **Controller** handles request, calls services
|
|
8. **Service** executes business logic
|
|
9. **Response** returned to client
|
|
|
|
## Configuration System
|
|
|
|
```
|
|
config.yaml
|
|
│
|
|
▼
|
|
generate-env.ts ──────────────────┐
|
|
│ │
|
|
▼ ▼
|
|
.env (root) honeycomb/.env
|
|
│ │
|
|
▼ ▼
|
|
docker-compose.yml Vite (frontend)
|
|
│
|
|
▼
|
|
hive/.env
|
|
│
|
|
▼
|
|
Express (backend)
|
|
```
|
|
|
|
## Docker Architecture
|
|
|
|
**Production:**
|
|
```
|
|
docker-compose.yml
|
|
├── honeycomb (frontend)
|
|
│ └── Dockerfile (multi-stage: build → nginx)
|
|
└── hive (backend)
|
|
└── Dockerfile (multi-stage: build → node)
|
|
```
|
|
|
|
**Development:**
|
|
```
|
|
docker-compose.yml + docker-compose.override.yml
|
|
├── honeycomb (frontend)
|
|
│ └── Dockerfile.dev (vite dev server)
|
|
└── hive (backend)
|
|
└── Dockerfile.dev (tsx watch)
|
|
```
|
|
|
|
## Scaling Considerations
|
|
|
|
### Horizontal Scaling
|
|
|
|
Both frontend and backend are stateless and can be scaled horizontally:
|
|
|
|
```yaml
|
|
# docker-compose.yml
|
|
services:
|
|
hive:
|
|
deploy:
|
|
replicas: 3
|
|
```
|
|
|
|
### Database
|
|
|
|
- Use connection pooling
|
|
- Consider read replicas for heavy read loads
|
|
- Implement caching layer if needed
|
|
|
|
### Caching
|
|
|
|
Options for caching:
|
|
- Redis for session/cache storage
|
|
- CDN for static assets
|
|
- HTTP caching headers
|
|
|
|
## Security
|
|
|
|
### Frontend
|
|
- Served over HTTPS (configure in nginx/reverse proxy)
|
|
- CSP headers via nginx
|
|
- No sensitive data in client code
|
|
|
|
### Backend
|
|
- Helmet.js for security headers
|
|
- CORS configured for specific origins
|
|
- Input validation with Zod
|
|
- JWT for authentication
|
|
- Rate limiting (configurable)
|
|
|
|
## Monitoring
|
|
|
|
### Health Checks
|
|
- `/health` - Overall health
|
|
- `/health/ready` - Ready to accept traffic
|
|
- `/health/live` - Process is alive
|
|
|
|
### Logging
|
|
- Structured JSON logs in production
|
|
- Configurable log levels
|
|
- Request logging via Morgan
|
|
|
|
## Development Workflow
|
|
|
|
1. Edit code in `honeycomb/` or `hive/`
|
|
2. Hot reload updates automatically
|
|
3. Run tests: `npm run test`
|
|
4. Lint: `npm run lint`
|
|
5. Build: `npm run build`
|