# heybuddy-nsk/nkblog architecture

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

- Interactive diagram: https://gitdiagram.com/heybuddy-nsk/nkblog
- Repository: https://github.com/heybuddy-nsk/nkblog

## Overview

##### Project type and purpose
- NKBlog is a full-stack social blogging application built with Flask (Python) on the backend and HTML/CSS on the frontend.
- Users can register/login, create and manage blog posts, comment, and receive email notifications.

##### File structure
- Top-level files:
- nkblog.py (entry point)
- Dockerfile, boot.sh (deployment)
- config.py (Flask configuration)
- requirements/ (dependencies for dev/prod/docker)
- app/ package:
- app/__init__.py: creates Flask app, registers Blueprints
- Blueprints:
– app/auth (registration/login views & forms)
– app/main (public views, index, post pages)
– app/api (JSON API endpoints for users, posts, comments, authentication)
- app/models.py: ORM models (User, Post, Comment, Follow, etc.)
- app/email.py: email-sending helper
- app/decorators.py & app/api/decorators.py: request guards (login-required, rate limiting)
- app/templates/ & app/static/: Jinja2 HTML templates and CSS
- migrations/: Alembic migration scripts and config

##### Key insights from README
- Stack: Flask + SQLite + Jinja2 + HTML/CSS
- Features: user auth, posts CRUD, comments, responsive design, user profiles, email confirmations
- Run process: set env vars → python nkblog.py

- Client (Browser/Mobile)
- Web Server / WSGI (Gunicorn/uWSGI or Flask’s built-in dev server)
- Flask Application (single container/service)
– Blueprints: Auth, Main (MVC views), API
– Business logic: forms, decorators, email module
– ORM layer: SQLAlchemy models
- Database (SQLite file)
- Migration Service (Alembic)
- External SMTP Mail Server
- (Optional) Reverse proxy / load balancer (Nginx, if Dockerized)

1. Client → HTTP → Reverse Proxy (Nginx) → WSGI Server
2. WSGI Server → Flask App
– URL routes dispatch to Blueprints
– Views process forms, call models, render templates or return JSON
3. Flask App ↔ SQLite (via SQLAlchemy)
4. Flask App → Alembic (for db schema migrations, invoked via CLI or at startup)
5. Flask App → SMTP Server (via app/email.py) → Client email inbox

c. Architectural patterns & principles
- Blueprint-based modularization: separates auth, main UI, and API layers
- MVC (views/templates/models) for HTML pages
- RESTful JSON API under /api for programmatic access
- Single-process service (could be scaled horizontally behind a load balancer)
- Configuration via config.py and environment variables

d. Key technologies & libraries
- Flask, Flask-Blueprints, Flask-Mail
- Jinja2 templating, HTML/CSS (static assets)
- SQLAlchemy ORM & Alembic migrations
- Docker (via Dockerfile) for containerization
- Requirements files to control dev/prod/docker deps

##### Elements
- Clear, descriptive labels for each component (e.g., “Flask: Auth Blueprint”)
- Client (light blue)
- Web server/WGSI (gray)
- Database & migrations (orange)
- External services (SMTP in yellow)

##### Detailed capture of essential elements
- How nkblog.py bootstraps the Flask app with config.py
- Blueprint registration (auth, main, api)
- Location of static files vs. templates vs. dynamic routes
- Optional Docker layer: Dockerfile → container → exposed ports

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Client
    subgraph "Client Layer"
        direction TB
        Browser["Browser (UI)"]:::client
        Mobile["Mobile App (UI)"]:::client
    end

    %% Web Tier
    subgraph "Web Tier"
        direction TB
        Nginx["Reverse Proxy / Nginx"]:::web
        WSGI["WSGI Server (Gunicorn/uWSGI)"]:::web
    end

    %% Application Service
    subgraph "Flask Application Service"
        direction TB
        Entry["nkblog.py"]:::appmod
        Config["config.py"]:::appmod

        subgraph "Blueprints"
            direction TB
            subgraph "Auth Blueprint"
                direction TB
                AuthInit["__init__.py"]:::appmod
                AuthViews["views.py"]:::appmod
                AuthForms["forms.py"]:::appmod
            end
            subgraph "Main (UI) Blueprint"
                direction TB
                MainInit["__init__.py"]:::appmod
                MainViews["views.py"]:::appmod
                MainForms["forms.py"]:::appmod
                MainErrors["errors.py"]:::appmod
            end
            subgraph "API Blueprint"
                direction TB
                APIInit["__init__.py"]:::appmod
                APIAuth["authentication.py"]:::appmod
                APIPosts["posts.py"]:::appmod
                APIComments["comments.py"]:::appmod
                APIUsers["users.py"]:::appmod
                APIDecorators["decorators.py"]:::appmod
                APIErrors["errors.py"]:::appmod
            end
        end

        Models["models.py"]:::appmod
        EmailMod["email.py"]:::appmod
        Decorators["decorators.py"]:::appmod
        APIDecos["app/api/decorators.py"]:::appmod

        subgraph "Assets"
            direction TB
            Templates["templates/"]:::appmod
            StaticCSS["static/style.css"]:::appmod
        end
    end

    %% Data & External Services
    subgraph "Data & External Services"
        direction TB
        DB["SQLite Database"]:::db
        subgraph "Migrations (Alembic)"
            direction TB
            AlembicIni["alembic.ini"]:::infra
            EnvPy["env.py"]:::infra
            ScriptMako["script.py.mako"]:::infra
            MigrationsReadme["README"]:::infra
        end
        SMTP["SMTP Mail Server"]:::external
    end

    %% Deployment & Env Setup
    subgraph "Deployment & Setup"
        direction TB
        Dockerfile["Dockerfile"]:::infra
        BootScript["boot.sh"]:::infra
        EnvScript["set_environment_variables.bat"]:::infra
        ReqCommon["requirements/common.txt"]:::infra
        ReqDev["requirements/dev.txt"]:::infra
        ReqProd["requirements/prod.txt"]:::infra
        ReqDocker["requirements/docker.txt"]:::infra
    end

    %% Connections
    Browser -->|HTTP| Nginx
    Mobile -->|HTTP| Nginx
    Nginx -->|proxy_pass| WSGI
    WSGI -->|calls| Entry
    Entry -->|loads| Config
    Entry -->|registers| AuthInit
    Entry -->|registers| MainInit
    Entry -->|registers| APIInit

    AuthViews -->|uses| AuthForms
    MainViews -->|uses| MainForms
    MainViews -->|raises| MainErrors
    APIAuth -->|guards| APIDecorators
    APIPosts -->|guards| APIDecorators

    Models -->|ORM| DB
    Entry -->|invokes migrations| EnvPy
    EnvPy -->|modifies| DB

    EmailMod -->|sends email via| SMTP

    Templates -->|rendered by| MainViews
    Templates -->|rendered by| AuthViews
    StaticCSS -->|served by| Nginx

    %% Deployment flows
    Dockerfile -->|builds| Entry
    BootScript -->|starts| WSGI
    EnvScript -->|sets vars| Entry
    ReqCommon -->|installs| Entry
    ReqDev -->|installs| Entry
    ReqProd -->|installs| Entry
    ReqDocker -->|installs| Entry

    %% Click Events
    click Entry "https://github.com/heybuddy-nsk/nkblog/blob/main/nkblog.py"
    click Config "https://github.com/heybuddy-nsk/nkblog/blob/main/config.py"
    click Dockerfile "https://github.com/heybuddy-nsk/nkblog/tree/main/Dockerfile"
    click BootScript "https://github.com/heybuddy-nsk/nkblog/blob/main/boot.sh"
    click EnvScript "https://github.com/heybuddy-nsk/nkblog/blob/main/set_environment_variables.bat"
    click ReqCommon "https://github.com/heybuddy-nsk/nkblog/blob/main/requirements/common.txt"
    click ReqDev "https://github.com/heybuddy-nsk/nkblog/blob/main/requirements/dev.txt"
    click ReqProd "https://github.com/heybuddy-nsk/nkblog/blob/main/requirements/prod.txt"
    click ReqDocker "https://github.com/heybuddy-nsk/nkblog/blob/main/requirements/docker.txt"
    click AuthInit "https://github.com/heybuddy-nsk/nkblog/blob/main/app/auth/__init__.py"
    click AuthViews "https://github.com/heybuddy-nsk/nkblog/blob/main/app/auth/views.py"
    click AuthForms "https://github.com/heybuddy-nsk/nkblog/blob/main/app/auth/forms.py"
    click MainInit "https://github.com/heybuddy-nsk/nkblog/blob/main/app/main/__init__.py"
    click MainViews "https://github.com/heybuddy-nsk/nkblog/blob/main/app/main/views.py"
    click MainForms "https://github.com/heybuddy-nsk/nkblog/blob/main/app/main/forms.py"
    click MainErrors "https://github.com/heybuddy-nsk/nkblog/blob/main/app/main/errors.py"
    click APIInit "https://github.com/heybuddy-nsk/nkblog/blob/main/app/api/__init__.py"
    click APIAuth "https://github.com/heybuddy-nsk/nkblog/blob/main/app/api/authentication.py"
    click APIPosts "https://github.com/heybuddy-nsk/nkblog/blob/main/app/api/posts.py"
    click APIComments "https://github.com/heybuddy-nsk/nkblog/blob/main/app/api/comments.py"
    click APIUsers "https://github.com/heybuddy-nsk/nkblog/blob/main/app/api/users.py"
    click APIDecorators "https://github.com/heybuddy-nsk/nkblog/blob/main/app/api/decorators.py"
    click APIErrors "https://github.com/heybuddy-nsk/nkblog/blob/main/app/api/errors.py"
    click Models "https://github.com/heybuddy-nsk/nkblog/blob/main/app/models.py"
    click EmailMod "https://github.com/heybuddy-nsk/nkblog/blob/main/app/email.py"
    click Decorators "https://github.com/heybuddy-nsk/nkblog/blob/main/app/decorators.py"
    click APIDecos "https://github.com/heybuddy-nsk/nkblog/blob/main/app/api/decorators.py"
    click Templates "https://github.com/heybuddy-nsk/nkblog/tree/main/app/templates/"
    click StaticCSS "https://github.com/heybuddy-nsk/nkblog/blob/main/app/static/style.css"
    click AlembicIni "https://github.com/heybuddy-nsk/nkblog/blob/main/migrations/alembic.ini"
    click EnvPy "https://github.com/heybuddy-nsk/nkblog/blob/main/migrations/env.py"
    click ScriptMako "https://github.com/heybuddy-nsk/nkblog/blob/main/migrations/script.py.mako"
    click MigrationsReadme "https://github.com/heybuddy-nsk/nkblog/tree/main/migrations/README"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0288D1,color:#000;
    classDef web fill:#E0E0E0,stroke:#616161,color:#000;
    classDef appmod fill:#E8F5E9,stroke:#388E3C,color:#000;
    classDef db fill:#FFE0B2,stroke:#FB8C00,color:#000;
    classDef external fill:#FFF9C4,stroke:#FBC02D,color:#000;
    classDef infra fill:#F3E5F5,stroke:#8E24AA,color:#000;
```
