Architektur-Übersicht¶

Audience: Dev, Ops
You will learn: - Systemkontext und Stakeholder des Icon-Tools - Container- und Komponenten-Architektur (C4 Level 1-2) - Runtime-Verhalten und Deployment-Szenarien - Architektonische Entscheidungen und Begründungen

Pre-requisites: - Grundverständnis von Web-Architekturen - Erfahrung mit Node.js und Python/Flask - Produktübersicht gelesen

Systemkontext (C4 Level 1)¶

C4Context
    title Systemkontext - ak Systems Icon Management Tool

    Person(dev, "Frontend-Entwickler", "Benötigt Icons für Web-Projekte")
    Person(designer, "UI/UX Designer", "Überblickt verfügbare Icons")
    Person(admin, "Admin", "Verwaltet Icon-Bibliothek")

    System(iconTool, "Icon Management Tool", "Zentrale Icon-Bibliothek mit Web-Interface")

    System_Ext(fontawesome, "FontAwesome", "Quell-Icon-Bibliothek")
    System_Ext(projects, "ak Systems Projekte", "Web-Anwendungen die Icons nutzen")

    Rel(dev, iconTool, "Downloads Icons, nutzt Web-Interface")
    Rel(designer, iconTool, "Durchsucht verfügbare Icons")
    Rel(admin, iconTool, "Verwaltet und erweitert Bibliothek")

    Rel(iconTool, fontawesome, "Extrahiert SVG-Icons")
    Rel(projects, iconTool, "Integriert heruntergeladene Icons")

Evidenz: replit.md:1-17, app.py:1-67, package.json:12-16

Container-Architektur (C4 Level 2)¶

C4Container
    title Container-Architektur

    Person(user, "Benutzer")

    Container_Boundary(iconTool, "Icon Management Tool") {
        Container(webapp, "Web Application", "Flask/Python", "Icon-Browser und API")
        Container(extractor, "Icon Extractor", "Node.js", "SVG-Extraktion aus FontAwesome")
        Container(storage, "File Storage", "File System", "SVG-Dateien und Metadaten")
    }

    System_Ext(fontawesome, "FontAwesome NPM", "Icon-Quell-Bibliothek")
    System_Ext(browser, "Web Browser", "Benutzer-Interface")

    Rel(user, browser, "Nutzt")
    Rel(browser, webapp, "HTTP/JSON API")
    Rel(webapp, storage, "Liest SVG-Dateien und Metadaten")
    Rel(extractor, fontawesome, "Importiert Icons")
    Rel(extractor, storage, "Schreibt SVG-Dateien")

Evidenz: app.py:15-43, extract-icons.js:1-270, icons.json:1-206

Komponenten-Architektur¶

1. Node.js Icon Extractor¶

graph TB
    A[FontAwesome Icons] --> B[Icon Mapper]
    B --> C[SVG Generator]
    C --> D[File Writer]
    D --> E[ZIP Creator]

    F[icons.json] --> B
    G[extract-icons.js] --> B

    subgraph "Output"
        H[SVG Files]
        I[ZIP Archive]
    end

    D --> H
    E --> I

Technische Details: - Sprache: JavaScript (Node.js) - Dependencies: FontAwesome SVG Core, Archiver - Input: FontAwesome Icon-Definitionen - Output: SVG-Dateien + ZIP-Archive

Evidenz: extract-icons.js:1-20, package.json:12-16

2. Flask Web Application¶

graph TB
    A[HTTP Request] --> B[Flask Router]
    B --> C[Icon Service]
    C --> D[File System]
    C --> E[JSON Metadata]

    subgraph "Endpoints"
        F[/ - Web Interface]
        G[/api/icons - JSON API]
        H[/icon/<name> - Single Icon]
    end

    B --> F
    B --> G
    B --> H

    I[Templates] --> F
    J[Static Files] --> F

Technische Details: - Sprache: Python 3.11+ - Framework: Flask 3.1.1+ - Rendering: Jinja2 Templates - API: RESTful JSON

Evidenz: app.py:1-67, pyproject.toml:6-8

3. File Storage Layer¶

static/
├── icons/              # 162 SVG-Dateien
│   ├── home.svg
│   ├── user.svg
│   └── ...
└── images/             # UI-Assets

icons.json              # Kategorie-Metadaten
templates/
└── index.html          # Web-Interface Template

Evidenz: ls-Output, icons.json:1-206

Runtime-Verhalten¶

Icon-Extraktion Workflow¶

sequenceDiagram
    participant Admin
    participant ExtractScript as extract-icons.js
    participant FontAwesome
    participant FileSystem

    Admin->>ExtractScript: node extract-icons.js
    ExtractScript->>FontAwesome: Import icon definitions
    FontAwesome-->>ExtractScript: SVG path data

    loop For each icon
        ExtractScript->>ExtractScript: Generate SVG with currentColor
        ExtractScript->>FileSystem: Write SVG file
    end

    ExtractScript->>FileSystem: Create ZIP archive
    ExtractScript-->>Admin: Success message + stats

Performance-Charakteristika: - Execution Time: ~2-3 Sekunden für 162 Icons - Output Size: 69KB ZIP-Archiv - Memory Usage: <50MB Peak

Evidenz: extract-icons.js:1-270, replit.md:89

Web-Interface Workflow¶

sequenceDiagram
    participant Browser
    participant Flask
    participant FileSystem
    participant IconJSON

    Browser->>Flask: GET /
    Flask->>FileSystem: List SVG files
    Flask->>IconJSON: Load categories
    Flask->>Flask: Merge icon data
    Flask-->>Browser: HTML + icon grid

    Browser->>Flask: GET /api/icons
    Flask->>FileSystem: Scan icons directory
    Flask->>IconJSON: Load metadata
    Flask-->>Browser: JSON response

Performance-Charakteristika: - Response Time: <100ms für Icon-Liste - Concurrent Users: 10+ bei single-thread Flask - Memory Usage: ~30MB Flask process

Evidenz: app.py:15-64

Deployment-Architektur¶

Development Setup¶

graph TB
    subgraph "Developer Machine"
        A[Local Repository]
        B[Node.js Runtime]
        C[Python Runtime]
        D[Local File System]
    end

    A --> B
    A --> C
    B --> D
    C --> D

    E[FontAwesome NPM] --> B
    F[Flask DevServer] --> C

Production Deployment¶

graph TB
    subgraph "Replit Environment"
        A[Git Repository]
        B[Nix Package Manager]
        C[Flask WSGI Server]
        D[Static File Serving]
    end

    subgraph "External"
        E[CDN/Browser Cache]
        F[FontAwesome Registry]
    end

    A --> C
    B --> C
    C --> D
    D --> E
    F --> B

Evidenz: pyproject.toml:1-8, replit environment

Architektonische Entscheidungen¶

1. Separierte Runtimes (Node.js + Python)¶

Entscheidung: Zwei separate Runtimes statt einer einheitlichen
Begründung: - Node.js: Optimal für FontAwesome-Integration (native NPM-Packages) - Python/Flask: Bewährte Lösung für Web-APIs und File-Serving - Separation of Concerns: Build-time (Node.js) vs. Runtime (Python)

Alternativen erwogen: - Pure Node.js mit Express → Komplexere File-Serving-Logik - Pure Python → FontAwesome-Integration über separate Tools

Evidenz: package.json:1-17, pyproject.toml:1-8

2. File-System als Primärer Storage¶

Entscheidung: SVG-Dateien im Dateisystem statt Database
Begründung: - Performance: Direktes Serving durch Webserver möglich - Einfachheit: Keine Database-Dependencies - Developer Experience: Icons können direkt inspiziert werden - Portabilität: Einfache ZIP-Verteilung

Trade-offs: - Metadata in separater JSON-Datei erforderlich - Keine komplexen Queries möglich

Evidenz: app.py:15-43, static/icons/ directory

3. Category-first Organization¶

Entscheidung: Kategorie-basierte Icon-Organisation statt Tag-System
Begründung: - User Experience: Einfache Navigation im Web-Interface - Maintenance: Klare Verantwortlichkeiten pro Kategorie - Performance: Efficient filtering ohne Database

Trade-offs: - Icons können nur einer Kategorie zugeordnet werden - Cross-cutting concerns schwieriger abbildbar

Evidenz: icons.json:1-206, app.py:22-43

4. SVG mit currentColor¶

Entscheidung: SVG fill="currentColor" statt feste Farben
Begründung: - CSS-Integration: Icons übernehmen Parent-Farbe - Theme-Kompatibilität: Dark/Light Mode automatisch - Bundle-Effizienz: Keine color-spezifischen Varianten nötig

Evidenz: extract-icons.js:88-94

Quality Attributes¶

Performance¶

Icon Extraction: <3s für komplette Bibliothek
Web Response: <100ms für Icon-Liste
Bundle Size: <70KB für alle Icons

Scalability¶

Icons: Unterstützt 500+ Icons ohne Performance-Degradation
Categories: Bis zu 50 Kategorien praktikabel
Concurrent Users: 20+ mit Standard-Flask-Deployment

Maintainability¶

Code Separation: Clear boundaries zwischen Extraction und Serving
Configuration: Centralized in extract-icons.js und icons.json
Documentation: Evidence-based docs mit Quellenangaben

Security¶

No User Input: Statische Datei-Generierung eliminiert Injection-Risiken
CORS-Ready: API kann Cross-Origin-Requests unterstützen
No Secrets: Keine sensiblen Daten im Repository

Evidenz: Gesamte Projektstruktur und -implementation

Zukünftige Architekturgrenzen¶

Scaling Bottlenecks¶

File System Limits: >1000 Icons könnten Directory-Performance beeinträchtigen
Single Process: Flask-App nicht horizontal skalierbar ohne Session-Store
Memory Usage: Komplette Icon-Liste wird in Memory gehalten

Evolution Paths¶

Database Migration: PostgreSQL für Metadata bei >500 Icons
Microservices: Separate Services für Extraction, Serving, Management
CDN Integration: Cloud Storage für Icon-Distribution

Related Documents: - ADR-0001: Technology Stack - Nonfunctional Requirements - Backend Overview