# marketcalls/sketchmaker architecture

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

- Interactive diagram: https://gitdiagram.com/marketcalls/sketchmaker
- Repository: https://github.com/marketcalls/sketchmaker

## Overview

##### Project Type and Purpose
- Sketch Maker AI is a full-stack, monolithic web application built with Flask (Python). It provides an AI-powered image and banner generation platform with features like virtual try-on, custom model training, an admin subscription system, and a responsive user interface.

##### File Structure Analysis
- Top-level directories:
- blueprints/ – Flask “controllers” organized by feature (auth, admin, gallery, virtual, magix, training, etc.)
- models/ & models.py – SQLAlchemy data models (users, subscriptions, content, API settings)
- migrations/ – Alembic migration scripts for schema evolution
- services/ – Pure-Python helper modules (image_optimizer, scheduler)
- static/ – Client-side assets (CSS, JS, images)
- templates/ – Jinja2 HTML templates grouped by feature
- server/ – System-level deploy scripts and service definitions
- docs/ – Project documentation and API references
- Core configuration: app.py (Flask app factory), extensions.py (Flask-Login, Limiter, APScheduler), requirements.txt, .env.sample

##### README Insights
- Backend: Flask 3.0.3, SQLAlchemy (SQLite/PostgreSQL), APScheduler for jobs, Cryptography (Fernet), OAuth integration
- Frontend: Tailwind CSS + DaisyUI, Vanilla ES6 JS modules, Fabric.js, GSAP
- External Integrations: OpenAI, Anthropic, Google Gemini, Groq, FAL, SMTP/Amazon SES, Google OAuth

##### Main Components
a. Client Layer (Browser)
- Static assets: HTML templates (Jinja2), CSS (Tailwind + custom), JS modules (image-gen-controls, form-handler, ui-updater)
- User interactions: Login, generate images, view gallery, admin panel
b. Application Layer (Flask)
- Blueprint modules: auth, admin, core, gallery, generate, virtual, magix, training, banner
- Shared services: extensions.py (DB connection, scheduler, rate limiter), services/image_optimizer.py, services/scheduler.py
- Business logic: credit system, model management, prompt generation, image processing
c. Data Layer
- Database: SQLAlchemy ORM → PostgreSQL/SQLite
- Migrations: Alembic migration scripts
- File storage: Local filesystem (static/uploads, training_files)
d. External Services
- AI Providers: OpenAI, Anthropic, Google Gemini, Groq, FAL (via REST/SDK)
- Email: SMTP server or Amazon SES
- OAuth: Google OAuth endpoints
e. Background Jobs
- APScheduler tasks: credit reset, training progress checks, cleanup jobs

##### Relationships and Data Flows
- User requests (via browser) → Flask route (blueprint)
- Route invokes controller → business logic → ORM models / services
- If AI generation: service layer calls external AI API → returns image(s) → post-processing (image_optimizer) → store in filesystem + metadata in DB → response to user
- Subscription management: DB triggers via APScheduler → update user credits at schedule → admin dashboard reads/writes DB
- Email flows: controllers call email-sending service → external SMTP/SES → user inbox

##### Architectural Patterns & Design Principles
- Modular MVC-style separation: Blueprints = Controllers; Models = ORM; Jinja2 Templates + static = Views
- Service layer for cross-cutting concerns (image optimization, scheduling, encryption)
- Configuration-driven model management and subscription system
- Secure design: role-based access, rate limiting, CSRF, Fernet encryption for API keys

##### Technologies and Frameworks to Annotate
- Flask, SQLAlchemy, Alembic, APScheduler, Cryptography (Fernet)
- Tailwind CSS, DaisyUI, Fabric.js, GSAP, Vanilla ES6 modules
- External APIs: OpenAI, Anthropic, Google Gemini, Groq, FAL
- Email: SMTP / Amazon SES; OAuth: Google

##### Final Advice
- Every module group (blueprints, services, models) without over-splitting trivial files
- How credit resets and training tasks run asynchronously
- Admin panel under Backend but highlight its management of API keys, models, and subscriptions
- Review the doc/README to ensure no major component is missing (e.g., server install scripts, subscription setup script)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Templates["Jinja2 Templates"]:::doc
        CSS["CSS (Tailwind & DaisyUI)"]:::frontend
        JS["JS Modules (ES6)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        App["Flask App Factory"]:::backend
        Ext["Extensions (DB, Auth, Scheduler, Rate Limiter)"]:::backend

        subgraph "Blueprints (Controllers)"
            direction TB
            AuthBP["Auth Blueprint"]:::backend
            AdminBP["Admin Blueprint"]:::backend
            CoreBP["Core Blueprint"]:::backend
            GalleryBP["Gallery Blueprint"]:::backend
            GenerateBP["Image Generation Controller"]:::backend
            VirtualBP["Virtual Try-On Blueprint"]:::backend
            MagixBP["Magix Feature Blueprint"]:::backend
            BannerBP["Banner Generation Blueprint"]:::backend
            TrainingBP["Training Blueprint"]:::backend
            PromptBP["Prompt Generation Module"]:::backend
            ImageUtilsBP["Image Utilities"]:::backend
        end

        subgraph "Services Layer"
            direction TB
            ImgOpt["Image Post-Processing Service"]:::service
            SchedSrv["Scheduler Support Service"]:::service
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["PostgreSQL/SQLite Database"]:::database
        Migrations["Alembic Migrations"]:::database
        FS["File Storage (uploads & training)"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        Anthropic["Anthropic API"]:::external
        Gemini["Google Gemini API"]:::external
        Groq["Groq API"]:::external
        FAL["FAL API"]:::external
        EmailSrv["SMTP / Amazon SES"]:::external
        OAuthSrv["Google OAuth"]:::external
    end

    %% Background Jobs
    subgraph "Background Jobs"
        direction TB
        APS["APScheduler"]:::job
    end

    %% Connections
    Templates -->|renders| App
    CSS -->|loaded by| App
    JS -->|calls| App

    App -->|uses| Ext
    App -->|registers| AuthBP
    App -->|registers| AdminBP
    App -->|registers| CoreBP
    App -->|registers| GalleryBP
    App -->|registers| GenerateBP
    App -->|registers| VirtualBP
    App -->|registers| MagixBP
    App -->|registers| BannerBP
    App -->|registers| TrainingBP
    App -->|uses| PromptBP
    App -->|uses| ImageUtilsBP

    AuthBP -->|invokes| ImgOpt
    GenerateBP -->|invokes| ImgOpt
    TrainingBP -->|invokes| SchedSrv
    APS -->|triggers tasks in| App

    App -->|read/write| DB
    App -->|migrate| Migrations
    App -->|store files| FS

    GenerateBP -->|calls| OpenAI
    GenerateBP -->|calls| Anthropic
    GenerateBP -->|calls| Gemini
    GenerateBP -->|calls| Groq
    GenerateBP -->|calls| FAL

    AdminBP -->|sends email via| EmailSrv
    AuthBP -->|auth via| OAuthSrv

    %% Click Events
    click App "https://github.com/marketcalls/sketchmaker/blob/master/app.py"
    click Ext "https://github.com/marketcalls/sketchmaker/blob/master/extensions.py"
    click AuthBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/auth.py"
    click AdminBP "https://github.com/marketcalls/sketchmaker/tree/master/blueprints/admin/"
    click CoreBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/core.py"
    click GalleryBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/gallery.py"
    click GenerateBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/generate.py"
    click VirtualBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/virtual.py"
    click MagixBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/magix.py"
    click BannerBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/banner.py"
    click TrainingBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/training.py"
    click PromptBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/prompt_generator.py"
    click ImageUtilsBP "https://github.com/marketcalls/sketchmaker/blob/master/blueprints/image_utils.py"
    click DB "https://github.com/marketcalls/sketchmaker/blob/master/models.py"
    click DB "https://github.com/marketcalls/sketchmaker/tree/master/models/"
    click Migrations "https://github.com/marketcalls/sketchmaker/tree/master/migrations/"
    click ImgOpt "https://github.com/marketcalls/sketchmaker/blob/master/services/image_optimizer.py"
    click SchedSrv "https://github.com/marketcalls/sketchmaker/blob/master/services/scheduler.py"
    click Templates "https://github.com/marketcalls/sketchmaker/tree/master/templates/"
    click CSS "https://github.com/marketcalls/sketchmaker/blob/master/static/css/custom.css"
    click JS "https://github.com/marketcalls/sketchmaker/blob/master/static/js/form-handler.js"
    click FS "https://github.com/marketcalls/sketchmaker/tree/master/static/training_files/"
    click SchedSrv "https://github.com/marketcalls/sketchmaker/blob/master/add_virtual_credits.py"
    click SchedSrv "https://github.com/marketcalls/sketchmaker/blob/master/setup_subscriptions.py"
    click APS "https://github.com/marketcalls/sketchmaker/blob/master/server/install.sh"
    click APS "https://github.com/marketcalls/sketchmaker/blob/master/server/sketchmaker.service"
    click APS "https://github.com/marketcalls/sketchmaker/blob/master/server/migrations/add_google_auth_support.sql"
    click APS "https://github.com/marketcalls/sketchmaker/blob/master/server/setup.md"
    click FS "https://github.com/marketcalls/sketchmaker/tree/master/docs/"
    
    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1
    classDef backend fill:#FCE4EC,stroke:#F48FB1,color:#880E4F
    classDef service fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20
    classDef database fill:#FFF3E0,stroke:#FFB74D,color:#E65100
    classDef storage fill:#F3E5F5,stroke:#BA68C8,color:#4A148C
    classDef external fill:#E0F7FA,stroke:#4DD0E1,color:#006064
    classDef job fill:#FFFDE7,stroke:#FFF176,color:#F57F17
    classDef doc fill:#ECEFF1,stroke:#90A4AE,color:#37474F
```
