# thangphan205/netconsole architecture

> Architecture diagram of the GitHub repository thangphan205/netconsole, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thangphan205/netconsole
- Repository: https://github.com/thangphan205/netconsole

## Overview

##### Project type and purpose
- This is a full‑stack network management tool (“Network Console Tool”) consisting of:
- A React/Vite single‑page application (frontend)
- A Python FastAPI service (backend)
- Network automation via Nornir/Netmiko
- A PostgreSQL database
- Docker Compose for development/production
- Traefik as a reverse proxy
- Purpose: provide a dashboard to view and configure switch interfaces, collect MAC/ARP/IP data, manage users/credentials, and push group configurations to Cisco/Juniper devices.

##### File structure
- Top‑level dirs:
- frontend/ – React SPA, Vite config, components, routes, OpenAPI‑generated client
- backend/ – FastAPI app, Alembic migrations, CRUD modules, automation scripts, email templates, tests
- docker‑compose*.yml – service definitions (frontend, backend, db, traefik)
- scripts/ – build/deploy/test helpers
- Backend layering:
- app/api/ – HTTP routes, dependency injection
- app/core/ – config, DB connection, security
- app/crud/ – data access
- app/automation/ – group‑config, inventory, device interactions
- app/models.py – ORM models
- alembic/ – schema migrations
- email‑templates/ – MJML templates and built HTML
- Frontend layering:
- src/routes/ – route components (login, admin, settings, entity pages)
- src/components/ – UI widgets and pages grouped by feature
- src/client/ – OpenAPI client classes/types for API calls
- src/hooks/ – auth and toast utilities

##### README for additional insights
- Confirms FastAPI + React + Docker Compose + Nornir
- Highlights features (switch info, interface config, data collection, group config)
- References environment variables, email notifications, Alembic, SMTP, Traefik dashboards

a. Main components
1. User’s Browser (React SPA)
2. Traefik Reverse Proxy
3. FastAPI Backend
– API layer (app/api)
– Business logic/CRUD layer (app/core, app/crud)
– Automation engine (app/automation using Nornir)
– Migrations (Alembic)
– Email service (SMTP)
4. PostgreSQL database
5. Network Devices (Cisco, Juniper)
6. (Optional) SMTP server
b. Relationships & data flow
- Browser → (HTTPS) → Traefik → FastAPI routes
- FastAPI ⇄ PostgreSQL for persistence (users, switches, interfaces, logs)
- FastAPI → SMTP to send emails (new account, reset password)
- FastAPI → Nornir → Network Devices to read/write configs
- Alembic invoked at startup for schema migrations
- Docker Compose brings up all services and networking
c. Architectural patterns & principles
- Layered architecture: API → service/CRUD → database
- Infrastructure as code: Docker Compose + Traefik
- Automated schema management: Alembic migrations
- Generated API client: OpenAPI → TypeScript
- Modular frontend with route-based code splitting
d. Key technologies/frameworks
- FastAPI, Pydantic, SQLAlchemy, Alembic
- React, Vite, TypeScript, JSX
- Nornir & Netmiko for device automation
- Docker, Docker Compose, Traefik
- PostgreSQL, SMTP (email)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React SPA)" 
        direction TB
        FE_Code["frontend/"]:::frontend
        FE_Main["Entry Point & Config\n(main.tsx, vite.config.ts)"]:::frontend
        FE_Routes["Routes"]:::frontend
        FE_Components["Components"]:::frontend
        FE_Client["OpenAPI Client"]:::frontend
    end

    %% Infrastructure Layer
    subgraph "Infrastructure" 
        direction TB
        Traefik["Traefik Reverse Proxy"]:::infra
        DockerCompose["Docker Compose"]:::infra
    end

    %% Backend Layer
    subgraph "Backend (FastAPI Service)"
        direction TB
        Backend_Code["backend/app/main.py"]:::backend
        API_Layer["API Layer\n(app/api/)"]:::backend
        Core["Core Services\n(app/core/)"]:::backend
        CRUD["CRUD Modules\n(app/crud/)"]:::backend
        Automation["Automation Engine\n(app/automation/)"]:::backend
        Inventory["Inventory Definitions\n(app/automation/inventory/)"]:::backend
        Models["ORM Models\n(app/models.py)"]:::backend
        Migrations["Alembic Migrations\n(app/alembic/versions/)"]:::backend
        EmailT["Email Templates\n(app/email-templates/)"]:::backend
        PreStart["Pre-Start Hook\n(backend_pre_start.py)"]:::backend
    end

    %% External Systems
    PostgreSQL["PostgreSQL Database"]:::external
    SMTP["SMTP Email Service"]:::external
    Devices["Network Devices\n(Cisco, Juniper)"]:::external

    %% Connections
    FE_Code -->|serves SPA via| Traefik
    Traefik -->|forwards HTTPS| Backend_Code
    Backend_Code --> API_Layer
    API_Layer --> Core
    Core --> CRUD
    Core --> Models
    Core --> Migrations
    Core --> EmailT
    Core --> Automation
    Automation --> Inventory
    API_Layer -->|DB access| PostgreSQL
    CRUD -->|DB read/write| PostgreSQL
    Migrations -->|apply schemas| PostgreSQL
    Core -->|send emails via| SMTP
    Automation -->|connects to| Devices
    DockerCompose -->|orchestrates| Traefik
    DockerCompose -->|orchestrates| Backend_Code
    DockerCompose -->|orchestrates| PostgreSQL

    %% Click Events - Frontend
    click FE_Code "https://github.com/thangphan205/netconsole/tree/master/frontend/"
    click FE_Main "https://github.com/thangphan205/netconsole/blob/master/frontend/src/main.tsx"
    click FE_Main "https://github.com/thangphan205/netconsole/blob/master/frontend/vite.config.ts"
    click FE_Routes "https://github.com/thangphan205/netconsole/tree/master/frontend/src/routes/"
    click FE_Components "https://github.com/thangphan205/netconsole/tree/master/frontend/src/components/"
    click FE_Client "https://github.com/thangphan205/netconsole/tree/master/frontend/src/client/"

    %% Click Events - Backend
    click Backend_Code "https://github.com/thangphan205/netconsole/blob/master/backend/app/main.py"
    click API_Layer "https://github.com/thangphan205/netconsole/tree/master/backend/app/api/"
    click Core "https://github.com/thangphan205/netconsole/tree/master/backend/app/core/"
    click CRUD "https://github.com/thangphan205/netconsole/tree/master/backend/app/crud/"
    click Automation "https://github.com/thangphan205/netconsole/tree/master/backend/app/automation/"
    click Inventory "https://github.com/thangphan205/netconsole/tree/master/backend/app/automation/inventory/"
    click Models "https://github.com/thangphan205/netconsole/blob/master/backend/app/models.py"
    click Migrations "https://github.com/thangphan205/netconsole/tree/master/backend/app/alembic/versions/"
    click EmailT "https://github.com/thangphan205/netconsole/tree/master/backend/app/email-templates/src/"
    click PreStart "https://github.com/thangphan205/netconsole/blob/master/backend/app/backend_pre_start.py"

    %% Click Events - Infrastructure
    click DockerCompose "https://github.com/thangphan205/netconsole/blob/master/docker-compose.yml"
    click Traefik "https://github.com/thangphan205/netconsole/blob/master/docker-compose.traefik.yml"

    %% Styles
    classDef frontend fill:#e0f7ff,stroke:#009ad6,stroke-width:2px;
    classDef backend fill:#e6ffe6,stroke:#00aa00,stroke-width:2px;
    classDef infra fill:#fff4e6,stroke:#ff9900,stroke-width:2px;
    classDef external fill:#f2f2f2,stroke:#666666,stroke-width:2px;
```
