Entwicklungsumgebung Setup

Audience: Dev
You will learn: - Lokale Entwicklungsumgebung für das Icon-Tool einrichten - Dependencies installieren und konfigurieren - Development-Server starten und testen - Debugging und Entwickler-Tools nutzen

Pre-requisites: - Git installiert und konfiguriert - Grundkenntnisse in Terminal/Command Line - Text-Editor oder IDE verfügbar

System-Anforderungen

Mindestvoraussetzungen

Component	Minimum	Empfohlen
Node.js	18.0+	20.0+
Python	3.11+	3.12+
RAM	2GB	4GB+
Disk Space	500MB	1GB+
OS	Windows 10, macOS 10.15, Ubuntu 20.04	Latest

Validierung

# Versionen prüfen
node --version     # Should be v18.0.0 or higher
npm --version      # Should be 8.0.0 or higher
python --version   # Should be 3.11.0 or higher
git --version      # Any recent version

Installation

1. Repository klonen

# Repository von GitHub klonen
git clone https://github.com/ak-systems/icon-tool.git
cd icon-tool

# Überprüfe Projektstruktur
ls -la
# Erwartete Dateien: app.py, extract-icons.js, package.json, pyproject.toml

Erwartetes Ergebnis:

drwxr-xr-x  static/
drwxr-xr-x  templates/
drwxr-xr-x  docs/
-rw-r--r--  app.py
-rw-r--r--  extract-icons.js
-rw-r--r--  package.json
-rw-r--r--  pyproject.toml
-rw-r--r--  icons.json

Evidenz: Project file structure, repository layout

2. Node.js Dependencies

# NPM-Packages installieren
npm install

# Erwartetes Ergebnis
npm list --depth=0

Expected Output:

icon-tool@1.0.0
├── @fortawesome/fontawesome-svg-core@7.0.0
├── @fortawesome/free-solid-svg-icons@7.0.0
└── archiver@7.0.1

Troubleshooting:

# Bei Fehlern: Node.js Version prüfen
node --version

# NPM Cache leeren
npm cache clean --force

# Dependencies neu installieren
rm -rf node_modules package-lock.json
npm install

Evidenz: package.json:12-16

3. Python Dependencies

Option A: pip (Standard)

# Python Dependencies installieren
pip install flask>=3.1.1

# Prüfen der Installation
python -c "import flask; print(f'Flask {flask.__version__} installed')"

Option B: uv (Empfohlen für Performance)

# uv installieren (falls nicht vorhanden)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Dependencies mit uv installieren
uv pip install flask>=3.1.1

# Virtual Environment (optional)
uv venv
source .venv/bin/activate  # Linux/macOS
# oder: .venv\Scripts\activate  # Windows
uv pip install flask>=3.1.1

Option C: poetry (Für Projektmanagement)

# poetry installieren
curl -sSL https://install.python-poetry.org | python3 -

# Dependencies installieren
poetry install

# Shell aktivieren
poetry shell

Validierung:

python -c "
import flask
import json
import os
print('✓ All Python dependencies available')
print(f'Flask version: {flask.__version__}')
"

Evidenz: pyproject.toml:6-8

Development-Server starten

1. Icons extrahieren

# FontAwesome Icons zu SVG-Dateien konvertieren
node extract-icons.js

Erwartetes Ergebnis:

FontAwesome Icons werden extrahiert...
✓ faMapMarkedAlt → map-marked-alt.svg
✓ faMap → map.svg
[... weitere Icons ...]
✓ 162 Icons erfolgreich extrahiert
✓ ZIP-Archiv erstellt: 69.234 bytes
📁 Datei: turkiye-atlasi-icons.zip

Troubleshooting:

# Bei Fehlern: FontAwesome-Installation prüfen
npm list @fortawesome/fontawesome-svg-core

# Icon-Mapping prüfen
grep -n "faIconName" extract-icons.js

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

2. Flask-Development-Server

# Flask-App starten
python app.py

Erwartetes Ergebnis:

 * Serving Flask app 'app'
 * Debug mode: on
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5000
 * Running on http://[your-ip]:5000
 * Press CTRL+C to quit

3. Funktionalität testen

# In neuem Terminal: API testen
curl http://localhost:5000/api/icons | jq '.metadata'

# Web-Interface testen
curl -I http://localhost:5000/
# Sollte HTTP/1.1 200 OK zurückgeben

Browser-Test: 1. Öffne http://localhost:5000 2. Überprüfe Icon-Grid-Anzeige 3. Teste Suchfunktion 4. Teste Kategorie-Filter

Evidenz: app.py:66-67, API endpoints

Development-Tools

1. Auto-Reload Setup

# Flask mit Auto-Reload (bereits aktiviert in app.py)
export FLASK_DEBUG=1
python app.py

# Node.js mit nodemon (optional)
npm install -g nodemon
nodemon extract-icons.js  # Bei Datei-Änderungen

2. Code-Formatierung

# Python: black formatter
pip install black
black app.py

# JavaScript: prettier
npm install -g prettier
prettier --write extract-icons.js

3. Linting

# Python: flake8
pip install flake8
flake8 app.py

# JavaScript: eslint
npm install -g eslint
eslint extract-icons.js

4. Testing-Setup

# Python Testing
pip install pytest
pytest tests/  # wenn Tests vorhanden

# JavaScript Testing
npm install -g jest
jest  # wenn Tests konfiguriert

Debugging

1. Flask-Debugging

# Debug-Informationen in app.py aktivieren
import logging
logging.basicConfig(level=logging.DEBUG)

app.logger.setLevel(logging.DEBUG)

# Oder via Environment
export FLASK_DEBUG=1
export FLASK_ENV=development

2. Icon-Extraktion debuggen

// In extract-icons.js: Debug-Output hinzufügen
console.log('Processing icon:', iconName);
console.log('Generated SVG:', svgString);

// Einzelne Icons testen
const { icon } = require('@fortawesome/fontawesome-svg-core');
const { faHome } = require('@fortawesome/free-solid-svg-icons');
console.log(icon(faHome));

3. Browser-DevTools

// Browser-Console für Frontend-Debugging
// Network-Tab für API-Calls überprüfen
// Elements-Tab für DOM-Inspektion
// Performance-Tab für Ladezeiten

// JavaScript-Debugging im Browser
debugger; // Breakpoint setzen
console.log('Icon data:', iconData);

Environment-Variablen

Development .env-Datei

# .env (nur für Development)
FLASK_ENV=development
FLASK_DEBUG=1
SECRET_KEY=dev-secret-key-not-for-production

# Optional: Performance-Tuning
ICON_CACHE_TIMEOUT=60
MAX_ICONS=500

# Laden in app.py
import os
from dotenv import load_dotenv  # pip install python-dotenv

load_dotenv()

app.config['SECRET_KEY'] = os.environ.get('SECRET_KEY', 'dev-key')

Production vs Development

Variable	Development	Production
FLASK_ENV	development	production
FLASK_DEBUG	True	False
SECRET_KEY	simple	secure random
CACHE_TIMEOUT	60s	300s

IDE-Konfiguration

Visual Studio Code

// .vscode/settings.json
{
  "python.defaultInterpreter": "./venv/bin/python",
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.formatting.provider": "black",
  "javascript.format.enable": true,
  "files.associations": {
    "*.svg": "xml"
  }
}

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Flask Debug",
      "type": "python",
      "request": "launch",
      "program": "app.py",
      "env": {
        "FLASK_DEBUG": "1"
      },
      "console": "integratedTerminal"
    }
  ]
}

PyCharm

1. Project Setup:
2. Open folder as project
3. Configure Python interpreter

4. Mark static and templates as resource folders

5. Run Configuration:

6. Script path: app.py
7. Environment variables: FLASK_DEBUG=1
8. Working directory: project root

Git-Workflow

Branch-Strategie

# Feature-Entwicklung
git checkout -b feature/new-icon-category
git add .
git commit -m "feat: Add healthcare icon category

- Added 8 new healthcare icons
- Updated icons.json with medical category
- Total icons: 162 → 170"

# Code-Review vorbereiten
git push origin feature/new-icon-category

Pre-commit Hooks

# Husky installieren (optional)
npm install -g husky
npx husky init

# Pre-commit Hook für Tests
echo "npm test && python -m pytest" > .husky/pre-commit
chmod +x .husky/pre-commit

Evidenz: Git workflow patterns, development best practices

Performance-Optimierung

1. Icon-Extraktion optimieren

// Parallel processing für große Icon-Sets
const cluster = require('cluster');
const numCPUs = require('os').cpus().length;

if (cluster.isMaster && numCPUs > 1) {
  // Split icon processing across workers
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }
} else {
  // Process subset of icons
}

2. Flask-Performance

# Caching für icon-Liste
from functools import lru_cache

@lru_cache(maxsize=1)
def get_cached_icon_list():
    return get_icon_list()

# Memory-Profiling
import psutil
print(f"Memory usage: {psutil.Process().memory_info().rss / 1024 / 1024:.1f} MB")

3. Frontend-Optimierung

// Icon-Lazy-Loading
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      loadIcon(entry.target);
    }
  });
});

// Service Worker für Caching
navigator.serviceWorker.register('/sw.js');

Troubleshooting

Häufige Probleme

Problem: "Module not found" Fehler

# Solution: Virtual Environment aktivieren
source venv/bin/activate
pip install flask

# Oder: System-wide Installation prüfen
which python
python -m pip list

Problem: Icons werden nicht extrahiert

# Solution: FontAwesome-Dependencies prüfen
npm list @fortawesome/fontawesome-svg-core
npm install --force

# Icon-Namen validieren
node -e "console.log(require('@fortawesome/free-solid-svg-icons').faHome)"

Problem: Flask-Server startet nicht

# Solution: Port-Konflikte prüfen
lsof -i :5000
# Prozess beenden oder anderen Port verwenden
python app.py --port 5001

Problem: Performance-Probleme

# Solution: Icon-Anzahl begrenzen
# In extract-icons.js: Weniger Icons definieren
# Oder: Caching aktivieren
export ENABLE_CACHING=true

Debug-Tools

# System-Informationen sammeln
python -c "
import sys, platform
print(f'Python: {sys.version}')
print(f'Platform: {platform.platform()}')
print(f'Architecture: {platform.architecture()}')
"

node -e "
console.log('Node.js:', process.version);
console.log('Platform:', process.platform);
console.log('Architecture:', process.arch);
"

# Dependency-Tree anzeigen
npm list
pip list

Evidenz: Common development issues and solutions

Nächste Schritte

Nach dem Setup

1. Backend-Dokumentation - Verstehe die Flask-Architektur
2. Frontend-Dokumentation - Lerne das Web-Interface kennen
3. API-Referenz - Nutze die programmatischen Schnittstellen
4. Administrator-Handbuch - Erweitere die Icon-Bibliothek

Development-Workflow

1. Feature-Branch erstellen: git checkout -b feature/xyz
2. Icons extrahieren: node extract-icons.js
3. Server starten: python app.py
4. Änderungen testen: Browser + API-Tests
5. Code committen: git commit -m "feat: xyz"
6. Pull Request: Code-Review und Merge

---

Setup-Validierung: - [ ] Node.js und Python Dependencies installiert - [ ] Icons erfolgreich extrahiert (162 SVG-Dateien) - [ ] Flask-Server läuft auf Port 5000 - [ ] Web-Interface zeigt Icon-Grid - [ ] API-Endpunkt /api/icons funktioniert