Skip to content

README.md

Latest commit

 

History

History
151 lines (118 loc) · 8.54 KB

README.md

File metadata and controls

151 lines (118 loc) · 8.54 KB
Raw

🚀 Blogify — Enterprise-Grade AI-Powered Digital Publishing Platform

Blogify is a high-performance, developer-first, and highly decoupled digital publishing platform. Crafted with a premium multi-package workspace architecture, it leverages a high-throughput FastAPI backend integrated with Google Gemini AI and a reactive, beautiful Flutter Web client.

FastAPI Flutter Docker Gemini

🏛️ Architectural Design & Tech Stack

The workspace is structured into highly decoupled, specialized packages to separate concerns and ensure scalable maintenance:

Blogify/
├── packages/
│   ├── api/                  # 🐍 Backend Service Layer (FastAPI)
│   │   ├── app/
│   │   │   ├── core/         # Configuration (Pydantic Settings), DB Engine, JWT Auth
│   │   │   ├── api/          # Routers (REST Endpoints for Auth, Articles, AI, Search)
│   │   │   ├── models/       # Database Schemas (SQLAlchemy ORM)
│   │   │   └── schemas/      # Contract Validation Models (Pydantic v2)
│   │   └── Dockerfile        # Container Build Specification
│   │
│   └── web/                  # 💙 Frontend Client Layer (Flutter Web)
│       ├── lib/
│       │   ├── core/         # Type-Safe ApiClient, Extensions, Theme Controllers
│       │   └── features/     # Feature Modules (Auth, Editor, Feed, Profile, Search)
│       └── pubspec.yaml
│
├── docker-compose.yml        # 🐳 Orchestration Blueprint
└── .env                      # 🔑 Workspace Environment Configurations

🐍 Backend Architecture (FastAPI & PostgreSQL)

  • Layered Architecture: Divided into strict routers, service handlers, model schemas, and data access layers.
  • Contract First: Enforces type safety and request/response integrity using Pydantic v2 validation.
  • Standardized REST Communication: Wraps all API payloads in a unified ResponseEnvelope<T> schema for consistent frontend serialization.
  • Secure Authentication Pipeline: Multi-tier authentication supporting stateless JWT tokens (with customizable refresh-expire lifecycles) alongside secure Google OAuth token validation.

💙 Frontend Architecture (Flutter Web & GetX)

  • Reactive MVC Pattern: Fully reactive state flows built using GetX Controllers to bind model modifications instantly to active UI components.
  • Type-Safe Network Engine: Features a custom HTTP network client based on Dio with global interception to automatically inject authentication headers and gracefully handle telemetry errors.
  • Responsive Editorial UI: Designed with fully adaptive layout constraints supporting responsive drawer navigations, collapsible sidebars, and fluid screen transitions.

🌟 Advanced Engineering Highlights

🤖 1. Semantic Gemini 2.5 Flash Integration

  • Cognitive Writing Suite: The backend proxy routes requests directly to the state-of-the-art gemini-2.5-flash model.
  • NLP Text Modification AST: Enables context-aware structural edits on articles. Users can perform advanced prompt execution to lengthen, condense, check grammar, or dynamically adjust styling and tone.
  • Cursor-Aware Formatting UX: Features sophisticated selection-capturing logic. Applying inline formatting automatically selects placeholders or places the active cursor outside the Markdown delimiters, providing an optimal editing experience.

🎨 2. High-Fidelity Glassmorphic UX/UI

  • Premium Visual Stacking: Interactive authorization layouts render multiple glowing color-blending neon blobs overlaid with a 130px BackdropFilter and custom dark gradient shaders to achieve sleek glassmorphism.
  • Dynamic Article Teaser Cards: Homepage article cards dynamically clamp titles to 2 lines and mute previews to 1 line, formatting the grid feed into a distraction-free layout.

✏️ 3. Integrated Profile & Editor State Routing

  • Direct In-Place Updating: Profile views automatically detect session owner relationships (isOwnProfile) and inject premium action overlays on the author's own articles.
  • Controller Synchronization: Triggers GetX initForEdit(article) to pre-populate text fields, tags, and cover images from database models.
  • Draft Cleansing: The global navigation bar triggers editorCtrl.reset() when initiating fresh draft sessions, protecting the state controller from cache pollution.

🔍 4. Asynchronous Debounced Query Processing

  • API Rate-Limiting: Incorporates a 600ms typing throttle (debounce) inside the frontend SearchController to shield database instances from rapid keyboard input spikes.

🐳 Dockerized Local Orchestration Pipeline

A Docker-based local development environment builds, runs, and monitors services cleanly without host machine dependency conflicts.

graph TD
    subgraph Net ["Container Networking (medium-network)"]
        Client["Browser / Flutter Client"] -->|"Port 8000"| FastAPI["FastAPI App Container (medium-api)"]
        FastAPI -->|"Port 5432"| DB[("PostgreSQL Database (medium-db)")]
        Admin["Developer / Admin"] -->|"Port 5050"| pgAdmin["pgAdmin Container (medium-pgadmin)"]
        pgAdmin --> DB
    end
    
    DB_Volume[("postgres_data (Persistent Volume)")] --- DB
    API_Volume["packages/api (Local Volume Mount)"] --- FastAPI
Loading

📦 Container Orchestration Details:

  1. FastAPI Application Service (medium-api):
    • Port Mapping: Maps local host port 8000 to internal container port 8000.
    • Hot-Reload Developer Experience (DX): Mounts ./packages/api:/app as a local host volume. Any backend python updates instantly trigger an internal live-reload without rebuilding the container.
    • Startup Health Checking: Pings http://localhost:8000/health to block downstream routing until the ASGI server is ready.
  2. PostgreSQL 16 Engine (medium-db):
    • Port Mapping: Exposes port 5432.
    • Persistent Storage: Links named volume postgres_data to /var/lib/postgresql/data ensuring database data survives restarts.
  3. pgAdmin 4 Administration Interface (medium-pgadmin):
    • Port Mapping: Visualizes databases on port 5050. Use the PGADMIN credentials configured in your .env (defaulting to admin@admin.com / admin123) to query PostgreSQL schemas visually.

⚙️ Quick Start Installation

1. Configure the Environment

Initialize a root-level .env file with the following specifications:

# Gemini AI Platform Credentials
GEMINI_API_KEY=your_gemini_api_key_here

# OAuth Identification
GOOGLE_CLIENT_ID=your_google_oauth_client_id_here

# PostgreSQL Container Credentials
POSTGRES_USER=your_postgres_user
POSTGRES_PASSWORD=your_postgres_password
POSTGRES_DB=your_postgres_db

# Custom database connection URL (for running outside Docker)
# DATABASE_URL=postgresql+asyncpg://your_postgres_user:your_postgres_password@localhost:5432/your_postgres_db

2. Boot the Backend Infrastructure

Initiate and build backend service nodes in detached mode:

docker compose up --build -d
  • Interactive API documentation (Swagger UI): Accessible at http://localhost:8000/docs.
  • Database Panel (pgAdmin): Accessible at http://localhost:5050.

3. Initialize the Frontend Client

# Navigate to the frontend directory
cd packages/web

# Pull dependencies
flutter pub get

# Launch the reactive web client locally in Google Chrome
flutter run -d chrome

🛠️ CLI Operations Cheat Sheet

Command Action
docker compose up --build -d Compiles modifications and launches backend infrastructure.
docker compose down Stops and gracefully cleans up active containers.
docker compose logs -f api Follows stdout/stderr streams from the FastAPI server.
docker compose exec db psql -U postgres -d medium_db Connects directly to the PostgreSQL console.
docker compose down -v Deletes persistent database storage volumes.