cisco-conf-generator/docs/ARCHITECTURE.md

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:

{
  "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