# index-null/snaf architecture

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

- Interactive diagram: https://gitdiagram.com/index-null/snaf
- Repository: https://github.com/index-null/snaf

## Overview

##### Project Type and Purpose
- This is a single‐process, standalone Windows background utility written in Python.
- It periodically (via a scheduler) checks campus‐network connectivity, automatically re‐authenticates via the Portal when disconnected, logs activity, and sends email notifications.
- It is distributed as a PyInstaller‐bundled executable; there is no separate frontend.

##### File Structure Analysis
- Top level:
- config.ini – user‐editable settings (credentials, email, intervals, log level)
- requirements.txt – Python dependencies
- src/ – core Python modules
– main.py – orchestrator (entry point)
– network_utils.py – connectivity checks and login routines (requests to Portal)
– email_utils.py – SMTP client (smtplib) for notifications
– logger_config.py – log setup (logging module)
- Assets directory and logs/app.log (created at runtime)
- No web UI or database—state is ephemeral, stored in memory and logs.

##### Key Components
a. Config Manager
- Reads config.ini (configparser) at startup.
b. Scheduler
- schedule library triggers “check” jobs at configured interval.
c. Network Checker
- network_utils → HTTP GET/HEAD to external site (e.g., httpbin.org or school portal)
d. Portal Authenticator
- network_utils → POST credentials to campus portal (requests)
e. Logger
- logger_config → writes to console and logs/app.log (file sink)
f. Email Notifier
- email_utils → SMTP session to external mail server (smtp.qq.com)
g. External Services
- Campus Portal Server (authentication endpoint)
- SMTP Server (QQ or other)
- External Internet Endpoint (for connectivity check)
h. OS Network Stack
- Underlying Windows networking, ipconfig invoked for diagnostics

##### Relationships & Data Flows
- On launch, main.py loads Config → init Logger → start Scheduler
- Scheduler → every “interval”:
1. Scheduler invokes Network Checker
2. If connectivity OK and first run or state changed → log status → maybe send “first success” email
3. If connectivity DOWN → Portal Authenticator attempts login
- On success/failure → log outcome → Email Notifier (with ipconfig output if needed)
- All modules share the same process; they interact via function calls and share the Logger instance.
- Config Manager is read‐only after startup; changes require restart.

##### Architectural Patterns & Principles
- Single responsibility modules (SRP): scheduling, network I/O, email, logging, config
- Observer pattern (Scheduler triggers subscribers)
- Stateless reconnection logic (state in memory only)
- Dependency injection via config object passed into modules (e.g., credentials, SMTP settings)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph for the standalone executable
    subgraph "Snaf Executable"
        direction TB
        CL["Config Loader"]:::infra
        SCH["Scheduler"]:::core
        NU["Network Utils"]:::core
        EU["Email Utils"]:::external
        LG["Logger"]:::infra
    end

    %% External resources
    CI["config.ini"]:::infra
    RF["requirements.txt"]:::infra
    AS["assets/"]:::infra
    LOGF["logs/app.log"]:::infra
    CP["Campus Portal Server"]:::external
    IE["External Internet Endpoint"]:::external
    SMTP["SMTP Server"]:::external

    %% Config and dependencies injection
    CI -->|1 load config| CL
    RF -.-> CL
    CL -->|provides config| SCH
    CL -->|provides config| NU
    CL -->|provides config| EU
    CL -->|provides config| LG

    %% Scheduler invokes network check
    SCH -->|2 check connectivity| NU

    %% Network Utils probes internet endpoint
    NU -->|3 probe| IE
    NU -->|4 authenticate| CP

    %% Logging interactions
    CL -->|write config load| LG
    SCH -->|write schedule start| LG
    NU -->|write probe result| LG
    NU -->|write auth result| LG
    EU -->|write email sent| LG
    LG -->|append| LOGF

    %% Portal auth result flows to email notifier
    NU -->|5 on failure/success| EU
    EU -->|6 send email| SMTP

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9,color:#1B4F72;
    classDef infra fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef external fill:#FDEBD0,stroke:#D35400,color:#7E5109;

    %% Click events
    click CI "https://github.com/index-null/snaf/blob/main/config.ini"
    click CL "https://github.com/index-null/snaf/blob/main/config.ini"
    click SCH "https://github.com/index-null/snaf/blob/main/src/main.py"
    click NU "https://github.com/index-null/snaf/blob/main/src/network_utils.py"
    click LG "https://github.com/index-null/snaf/blob/main/src/logger_config.py"
    click EU "https://github.com/index-null/snaf/blob/main/src/email_utils.py"
    click AS "https://github.com/index-null/snaf/tree/main/assets/"
    click RF "https://github.com/index-null/snaf/blob/main/requirements.txt"
```
