# ramilevi1/qt-ride architecture

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

- Interactive diagram: https://gitdiagram.com/ramilevi1/qt-ride
- Repository: https://github.com/ramilevi1/qt-ride

## Overview

##### Project Type and Purpose
- This is a full-stack, Flask-based carpooling application (“QT-ride”) with an N-tier microservices architecture.
- Core features: user authentication, ride offering, ride searching, blog publishing and parsing, newsletter signup/delivery, and contact-us email.

##### File Structure Analysis
- Top-level:
- app.py (main Flask entrypoint)
- static/ and templates/ (frontend assets and Jinja templates)
- auth_service/, offer_service/, search_service/, user_profile/ (each a self-contained Flask microservice with its own venv, app.py, database, migrations)
- shared_instance/ (common models and shared SQLite DB)
- scripts: parse_blogs.py, newletterScript.py (batch processing), ride_migrations/, my_playwright_tests/ (E2E tests)
- Other: database.py and models.py at root for central logic, README specifying architecture and tech stack.

##### README Insights
- Declares N-tier microservices: Client → Authentication, OfferRide, SearchRide services → their own SQLite DBs
- Lists tech: Flask, Flask-SQLAlchemy, Flask-Migrate, Flask-Login, SQLite, Jinja, vanilla JS, Ajax, Playwright tests.

##### Main Components
a. Client (Web Browser / Mobile)
- Renders HTML/CSS/JS from static/ and templates/
- Initiates HTTP(S) requests to the gateway or directly to microservices
b. API Gateway / Main Flask App (app.py)
- Single entrypoint that routes requests to microservices or serves UI
c. Microservices
1) Authentication Service (auth_service/app.py + auth_service/auth_service.db)
2) OfferRide Service (offer_service/app.py + offer_service/*.db)
3) SearchRide Service (search_service/app.py + search_service/*.db)
4) UserProfile Service (user_profile/app.py + user_profile/*.db)
d. Shared Data Layer
- shared_instance/database.py + ride.db (optional consolidated DB)
- Migrations directories show Flask-Migrate usage per service
e. Batch/Background Processes
- parse_blogs.py (scrapes templates/blogs → shared DB)
- newletterScript.py (sends emails via Flask-Mail or SMTP)
f. External Services
- Email SMTP server (for contact-us and newsletter delivery)

##### Relationships and Data Flows
- Client → HTTPS → API Gateway / Main App
- API Gateway → internal HTTP calls or Flask Blueprints to microservices
- Each microservice ↔ its own SQLite DB via SQLAlchemy
- parse_blogs.py reads service templates/blog files → writes parsed content into a DB (could be shared_instance)
- newletterScript.py reads newsletter signup DB entries → sends emails via SMTP
- playwrite tests simulate end-to-end client interactions with the deployed app

##### Architectural Patterns and Design Principles
- N-Tier + Microservices: separation of concerns by domain (auth, rides, profiles)
- Service per database: each Flask service manages its own persistence layer
- Batch processing for blogs and newsletters is decoupled from request path
- Shared library (shared_instance) for common models to avoid duplication
- CI workflows defined in .github/workflows for tests and linting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/UI Layer
    subgraph "Client/UI" 
        direction TB
        Static["static/"]:::frontend
        Templates["templates/"]:::frontend
    end

    E2ETests["Playwright E2E Tests"]:::test
    E2ETests -->|simulates user| Static
    E2ETests -->|simulates user| Templates

    %% API Gateway Layer
    Gateway["API Gateway<br/>app.py"]:::gateway

    Static -->|serves UI| Gateway
    Templates -->|serves UI| Gateway

    %% Microservices Layer
    subgraph "Microservices" 
        direction TB
        %% Authentication Service
        AuthService["Auth Service<br/>(Flask)"]:::backend
        AuthDB["Auth DB<br/>(SQLite)"]:::db
        AuthMigs["auth_service/migrations/"]:::migrations

        %% OfferRide Service
        OfferService["OfferRide Service<br/>(Flask)"]:::backend
        OfferMigs["offer_service/migrations/"]:::migrations
        OfferVenv["offer_service/venv"]:::env

        %% SearchRide Service
        SearchService["SearchRide Service<br/>(Flask)"]:::backend
        SearchMigs["search_service/migrations/"]:::migrations
        SearchVenv["search_service/venv"]:::env

        %% UserProfile Service
        ProfileService["UserProfile Service<br/>(Flask)"]:::backend
        ProfileDB["user_profile DB<br/>(SQLite)"]:::db
        ProfileMigs["user_profile/migrations/"]:::migrations
    end

    Gateway -->|REST API calls| AuthService
    Gateway -->|REST API calls| OfferService
    Gateway -->|REST API calls| SearchService
    Gateway -->|REST API calls| ProfileService

    AuthService -->|SQLAlchemy ↔ SQLite| AuthDB
    AuthService -->|uses migrations| AuthMigs
    OfferService -->|uses migrations| OfferMigs
    SearchService -->|uses migrations| SearchMigs
    ProfileService -->|SQLAlchemy ↔ SQLite| ProfileDB
    ProfileService -->|uses migrations| ProfileMigs

    %% Shared Library & DB
    SharedLib["shared_instance<br/>(common models)"]:::shared
    SharedDB["ride.db"]:::db
    SharedMigs["ride_migrations/"]:::migrations

    AuthService -->|imports| SharedLib
    OfferService -->|imports| SharedLib
    SearchService -->|imports| SharedLib
    ProfileService -->|imports| SharedLib
    SharedLib -->|central DB| SharedDB
    SharedDB -->|versioned by| SharedMigs

    %% Batch Processes
    ParseBlogs["parse_blogs.py"]:::batch
    Newsletter["newletterScript.py"]:::batch
    ParseBlogs -.->|reads templates/blogs| SharedDB
    Newsletter -->|sends emails| SMTP["SMTP Server"]:::external

    %% Click Events
    click Static "https://github.com/ramilevi1/qt-ride/tree/main/static/"
    click Templates "https://github.com/ramilevi1/qt-ride/tree/main/templates/"
    click E2ETests "https://github.com/ramilevi1/qt-ride/tree/main/my_playwright_tests/tests/"
    click Gateway "https://github.com/ramilevi1/qt-ride/blob/main/app.py"
    click AuthService "https://github.com/ramilevi1/qt-ride/blob/main/auth_service/app.py"
    click AuthDB "https://github.com/ramilevi1/qt-ride/blob/main/auth_service/instance/auth_service.db"
    click AuthMigs "https://github.com/ramilevi1/qt-ride/tree/main/auth_service/migrations/"
    click OfferService "https://github.com/ramilevi1/qt-ride/blob/main/offer_service/app.py"
    click OfferMigs "https://github.com/ramilevi1/qt-ride/tree/main/offer_service/migrations/"
    click OfferVenv "https://github.com/ramilevi1/qt-ride/tree/main/offer_service/venv"
    click SearchService "https://github.com/ramilevi1/qt-ride/blob/main/search_service/app.py"
    click SearchMigs "https://github.com/ramilevi1/qt-ride/tree/main/search_service/migrations/"
    click SearchVenv "https://github.com/ramilevi1/qt-ride/tree/main/search_service/venv"
    click ProfileService "https://github.com/ramilevi1/qt-ride/blob/main/user_profile/app.py"
    click ProfileDB "https://github.com/ramilevi1/qt-ride/blob/main/user_profile/instance/user_profile.db"
    click ProfileMigs "https://github.com/ramilevi1/qt-ride/tree/main/user_profile/migrations/"
    click SharedLib "https://github.com/ramilevi1/qt-ride/blob/main/shared_instance/models.py"
    click SharedDB "https://github.com/ramilevi1/qt-ride/blob/main/shared_instance/ride.db"
    click SharedMigs "https://github.com/ramilevi1/qt-ride/tree/main/ride_migrations/"
    click ParseBlogs "https://github.com/ramilevi1/qt-ride/blob/main/parse_blogs.py"
    click Newsletter "https://github.com/ramilevi1/qt-ride/blob/main/newletterScript.py"
    click SMTP "https://github.com/ramilevi1/qt-ride/tree/main/n/a"

    %% Styles
    classDef frontend fill:#E8F1F2,stroke:#333,stroke-width:1px
    classDef gateway fill:#D6EAF8,stroke:#333,stroke-width:1px
    classDef backend fill:#FCF3CF,stroke:#333,stroke-width:1px
    classDef db fill:#FADBD8,stroke:#333,stroke-width:1px
    classDef migrations fill:#D5F5E3,stroke:#333,stroke-width:1px
    classDef env fill:#F0F3F4,stroke:#333,stroke-width:1px
    classDef shared fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef batch fill:#E8DAEF,stroke:#333,stroke-width:1px
    classDef external fill:#D5D8DC,stroke:#333,stroke-width:1px
    classDef test fill:#F5CBA7,stroke:#333,stroke-width:1px
```
