# blackscythe123/skywings architecture

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

- Interactive diagram: https://gitdiagram.com/blackscythe123/skywings
- Repository: https://github.com/blackscythe123/skywings

## Overview

##### Project type and purpose
- SkyWings is a full-stack flight booking web application built on Flask (Python) with a Bootstrap/JS frontend.
- It supports user authentication, flight search/booking, seat selection, payment processing (Stripe), AI chatbot assistance, weather monitoring, background status updates, email notifications, reporting, and an admin dashboard.

##### File structure
- Top-level “skywings/” directory:
- app.py – Flask app factory, config
- routes.py & chatbot_routes.py – main and chatbot blueprints
- models.py – SQLAlchemy ORM models
- extensions.py – Flask extensions (db, mail, session)
- utils.py – pricing, seat-map helpers
- tasks.py, weather_monitor.py, flight_status_updater.py – background threads/services
- large_injection.py, fix_frequent_flyer_status.py, seed.py – data-injection scripts
- static/ (css, js) & templates/ (base, user pages, admin pages)
- requirements.txt, migrations/, recreate_db.py
- Patterns:
- MVC-style separation (templates/views, models)
- Blueprint modules for grouping routes (chatbot, admin vs user)
- Background services run alongside main app via threads or separate scripts

##### Key insights from README
- Backend: Flask + SQLAlchemy + Flask-Mail
- Frontend: HTML/CSS/JS + Bootstrap
- External services: Stripe (payments), OpenWeather (weather), OpenRouter/DeepSeek (AI chatbot), SMTP email, wkhtmltopdf/pdfkit
- Background processing: thread-based weather checks and flight status updates
- Admin dashboard for managing flights/users/bookings/reports
- Frequent flyer program logic and bulk-fix scripts

a. Main components
1. Client Browser (User/UI)
– Static assets (JS, CSS) for SPA-like interactions: flight search, seat map, booking forms
2. Flask Web Server
– HTTP(s) endpoints via Blueprints:
- User routes (routes.py)
- Admin routes
- Chatbot routes (chatbot_routes.py)
– PDF generation service
– Background scheduler (weather_monitor, flight_status_updater, tasks.py)
3. Database
– PostgreSQL/SQLite accessed via SQLAlchemy (models.py, migrations/)
4. External Services
– Stripe API (payment processing)
– OpenWeather API (weather data)
– OpenRouter/DeepSeek (AI for chatbot)
– Email SMTP (Flask-Mail)
– wkhtmltopdf (PDF docs)
b. Relationships & interactions
– Browser → Flask (HTTP JSON/HTML)
– Flask ↔ Database (CRUD via SQLAlchemy)
– Flask → Stripe (REST) → Stripe Webhooks → Flask
– Flask → OpenWeather & OpenRouter APIs
– Flask → SMTP Email server
– Background threads (weather_monitor, flight_status_updater) poll External APIs and update DB
– Data-injection scripts run as standalone processes to seed/fix DB
c. Architectural patterns & principles
– MVC (models.py + templates + routes)
– Modular blueprint design for separation of concerns (chatbot, user, admin)
– Layered architecture: Presentation (templates/static), Application (Flask views, services), Data (ORM)
– Asynchronous/background processing for non-blocking tasks
– Third-party API integration points clearly isolated in service modules (weather_service.py, chatbot.py)
d. Key technologies/frameworks
– Flask, SQLAlchemy, Flask-Mail, Bootstrap, JavaScript
– Stripe SDK, OpenWeather SDK, OpenRouter integration
– Threading or Celery-like pattern (in-process)

##### Final recommendations
- Be very detailed: break the Flask backend into sub-components (API layer, business logic, data layer, extensions).
- Background vs synchronous flows clearly.
- Avoid unnecessary complexity—focus on the essential modules and their interactions as outlined above.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Frontend Layer"
        Browser["Client Browser"]:::frontend
        StaticAssets["Static Assets (JS/CSS)"]:::frontend
        Templates["Frontend Templates"]:::frontend
    end

    subgraph "Backend Layer"
        AppFactory["Flask App Factory\n(Config)"]:::backend
        Routes["User/Admin Blueprints"]:::backend
        ChatbotRoutes["Chatbot Endpoints"]:::backend
        Extensions["Flask Extensions"]:::backend
        Utils["Pricing & SeatMap Helpers"]:::backend
        Models["ORM Models"]:::backend
        Migrations["Migrations"]:::backend
        Tasks["Background Scheduler"]:::backend
        WeatherService["Weather Service"]:::backend
        FlightUpdater["Flight Status Updater Service"]:::backend
        ChatbotIntegration["AI Chatbot Integration"]:::backend
    end

    subgraph "Data Layer"
        Database[(Database)]:::data
    end

    subgraph "Background Services"
        WeatherMonitor["Weather Monitor"]:::background
        FlightStatusUpdater["Flight Status Updater"]:::background
    end

    subgraph "External Services"
        Stripe["Stripe API"]:::external
        OpenWeather["OpenWeather API"]:::external
        AIAPI["OpenRouter/DeepSeek AI"]:::external
        SMTP["SMTP Email"]:::external
        PDFGen["wkhtmltopdf/PDFKit"]:::external
    end

    Browser -->|"HTTPS/HTML, JSON"| AppFactory
    Browser -->|Static files| StaticAssets
    Browser -->|"Renders"| Templates

    AppFactory --> Routes
    AppFactory --> ChatbotRoutes
    AppFactory --> Extensions
    AppFactory --> Utils
    AppFactory --> Models

    Routes -->|"SQLAlchemy CRUD"| Database
    ChatbotRoutes --> ChatbotIntegration
    ChatbotIntegration -->|"REST"| AIAPI
    ChatbotRoutes -->|"Session/JWT"| Database

    AppFactory -->|"Generate PDF"| PDFGen
    AppFactory -->|"Process Payment"| Stripe
    Stripe -->|"Webhooks"| AppFactory

    AppFactory -->|"Fetch Weather"| OpenWeather
    WeatherMonitor --> WeatherService
    WeatherService --> OpenWeather
    WeatherMonitor -->|"poll every 5m"| Database

    Tasks --> WeatherMonitor
    Tasks --> FlightStatusUpdater
    FlightStatusUpdater -->|"update status"| Database

    AppFactory -->|"Send Email"| SMTP

    %% Click Events
    click AppFactory "https://github.com/blackscythe123/skywings/blob/main/skywings/app.py"
    click Routes "https://github.com/blackscythe123/skywings/blob/main/skywings/routes.py"
    click ChatbotRoutes "https://github.com/blackscythe123/skywings/blob/main/skywings/chatbot_routes.py"
    click Extensions "https://github.com/blackscythe123/skywings/blob/main/skywings/extensions.py"
    click Utils "https://github.com/blackscythe123/skywings/blob/main/skywings/utils.py"
    click Models "https://github.com/blackscythe123/skywings/blob/main/skywings/models.py"
    click Migrations "https://github.com/blackscythe123/skywings/tree/main/skywings/migrations/"
    click Tasks "https://github.com/blackscythe123/skywings/blob/main/skywings/tasks.py"
    click WeatherMonitor "https://github.com/blackscythe123/skywings/blob/main/skywings/weather_monitor.py"
    click WeatherService "https://github.com/blackscythe123/skywings/blob/main/skywings/weather_service.py"
    click FlightStatusUpdater "https://github.com/blackscythe123/skywings/blob/main/skywings/flight_status_updater.py"
    click ChatbotIntegration "https://github.com/blackscythe123/skywings/blob/main/skywings/chatbot.py"
    click StaticAssets "https://github.com/blackscythe123/skywings/tree/main/skywings/static/js/"
    click Templates "https://github.com/blackscythe123/skywings/tree/main/skywings/templates/"

    %% Styles
    classDef frontend fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef backend fill:#E0F7FA,stroke:#0277BD,color:#01579B
    classDef data fill:#FFEBEE,stroke:#C62828,color:#B71C1C
    classDef external fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef background fill:#ECEFF1,stroke:#546E7A,color:#37474F
```
