183 lines
7.1 KiB
Markdown
183 lines
7.1 KiB
Markdown
# Architecture Overview
|
|
|
|
## System Design
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ FRONTEND (React/TS) │
|
|
│ - Configuration Builder GUI │
|
|
│ - Real-time CLI Preview │
|
|
│ - Validation Feedback │
|
|
│ - Push Confirmation Modal │
|
|
└──────────────────────┬──────────────────────────────────────┘
|
|
│ REST API (JSON)
|
|
↓
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ BACKEND (FastAPI) │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ API ROUTERS │ │
|
|
│ │ - auth.py (JWT login) │ │
|
|
│ │ - projects.py (CRUD) │ │
|
|
│ │ - devices.py (CRUD) │ │
|
|
│ │ - configurations.py (CRUD + validation + generate) │ │
|
|
│ │ - push.py (SSH execution) │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ BUSINESS LOGIC │ │
|
|
│ │ - CLI Generation (generators.py + renderer.py) │ │
|
|
│ │ - Validation (validation/__init__.py) │ │
|
|
│ │ - SSH Push (ssh/__init__.py + Netmiko) │ │
|
|
│ │ - Security (core/security.py) │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌─────────────────────────────────────────────────────┐ │
|
|
│ │ DATA ACCESS │ │
|
|
│ │ - SQLAlchemy ORM │ │
|
|
│ │ - Pydantic Schemas │ │
|
|
│ └─────────────────────────────────────────────────────┘ │
|
|
└──────────────────────┬──────────────────────────────────────┘
|
|
│
|
|
┌──────────────┼──────────────┐
|
|
↓ ↓ ↓
|
|
┌────────┐ ┌──────────┐ ┌──────────┐
|
|
│PostgreSQL │ │ Cisco │ │SSH Audit│
|
|
│Database │ │ Devices│ │ Log │
|
|
│Users, │ │ via SSH│ │ │
|
|
│Projects, │ │ │ │ │
|
|
│Configs │ │ │ │ │
|
|
└────────┘ └──────────┘ └──────────┘
|
|
```
|
|
|
|
## Data Flow: Configuration Push
|
|
|
|
```
|
|
1. User builds config in GUI
|
|
↓
|
|
2. Frontend sends to /configurations/{id}/validate
|
|
↓
|
|
3. Backend validates:
|
|
- VLAN refs
|
|
- IP overlaps
|
|
- Interface config
|
|
↓
|
|
4. Frontend displays errors/warnings
|
|
↓
|
|
5. User corrects & clicks "Generate CLI"
|
|
↓
|
|
6. Frontend calls /configurations/{id}/generate
|
|
↓
|
|
7. Backend renders CLI in correct order:
|
|
- hostname
|
|
- vlans
|
|
- interfaces
|
|
- routing
|
|
- nat
|
|
- acls
|
|
↓
|
|
8. Frontend shows CLI preview
|
|
↓
|
|
9. User confirms push (with SSH credentials)
|
|
↓
|
|
10. Frontend calls POST /configurations/{id}/push
|
|
↓
|
|
11. Backend:
|
|
a) Validates SSH credentials
|
|
b) Gets backup (show running-config)
|
|
c) Sends commands via Netmiko
|
|
d) Verifies success
|
|
e) Saves config (write memory)
|
|
f) Logs to push_logs table
|
|
↓
|
|
12. Frontend shows result (success/failure)
|
|
```
|
|
|
|
## Key Design Decisions
|
|
|
|
### CLI Generation
|
|
- **Deterministic**: Same config always produces same CLI
|
|
- **Ordered**: Commands in proper Cisco sequence
|
|
- **Idempotent**: Commands can be rerun safely
|
|
- **Modular**: Each feature (VLAN, interface) in separate generator
|
|
|
|
### Validation
|
|
- **Comprehensive**: Checks VLAN refs, IP overlap, config consistency
|
|
- **Warnings + Errors**: Separates blocker issues from recommendations
|
|
- **Extensible**: Easy to add new validators
|
|
|
|
### SSH Security
|
|
- **In-memory only**: Credentials never stored
|
|
- **Per-push**: Credentials provided at push time
|
|
- **Timeout**: 30s max connection time
|
|
- **Audit trail**: All commands logged with output
|
|
|
|
### Database
|
|
- **Relational**: User → Project → Device → Configuration → PushLog
|
|
- **Ownership**: Each project has owner (user)
|
|
- **Audit**: Push logs never deleted (compliance)
|
|
|
|
## Deployment Architecture
|
|
|
|
### Local Development
|
|
```
|
|
Frontend (Vite) Backend (FastAPI) Database (PostgreSQL)
|
|
http://localhost:3000 http://localhost:8000 localhost:5432
|
|
```
|
|
|
|
### Docker Compose
|
|
```
|
|
frontend:3000 → api:8000 → postgres:5432
|
|
```
|
|
|
|
### Production (Kubernetes future)
|
|
```
|
|
Ingress → Frontend Service → API Service → Database
|
|
```
|
|
|
|
## API Authentication
|
|
|
|
All endpoints except `/health`, `/auth/register`, `/auth/login` require:
|
|
```
|
|
Authorization: Bearer <JWT_TOKEN>
|
|
```
|
|
|
|
JWT includes:
|
|
- `sub`: user email
|
|
- `exp`: expiration time
|
|
- Signed with SECRET_KEY
|
|
|
|
## Error Handling
|
|
|
|
All errors return JSON:
|
|
```json
|
|
{
|
|
"detail": "Human-readable error message"
|
|
}
|
|
```
|
|
|
|
HTTP status codes:
|
|
- 200: Success
|
|
- 400: Bad request (validation error)
|
|
- 401: Unauthorized (missing/invalid token)
|
|
- 403: Forbidden (access denied)
|
|
- 404: Not found
|
|
- 500: Server error
|
|
|
|
## Performance Considerations
|
|
|
|
### Frontend
|
|
- React lazy loading for config pages
|
|
- CLI preview debounced (500ms)
|
|
- Validation on blur
|
|
|
|
### Backend
|
|
- Database indexes on: user email, project owner, device IP
|
|
- Connection pooling (PostgreSQL)
|
|
- Async/await for SSH (Netmiko in thread pool)
|
|
|
|
### SSH
|
|
- Timeout 30s to prevent hanging
|
|
- Batch commands into single connection
|
|
- Log all output for troubleshooting
|