# 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