██████╗ █████╗ ██████╗ █████╗ ███████╗██╗ ██████╗ ██╗ ██╗ ██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔════╝██║ ██╔═══██╗██║ ██║ ██████╔╝███████║██████╔╝███████║█████╗ ██║ ██║ ██║██║ █╗ ██║ ██╔═══╝ ██╔══██║██╔══██╗██╔══██║██╔══╝ ██║ ██║ ██║██║███╗██║ ██║ ██║ ██║██║ ██║██║ ██║██║ ███████╗╚██████╔╝╚███╔███╔╝ ╚═╝ ╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝ ╚══════╝ ╚═════╝ ╚══╝╚══╝

✍️ ParaFlow AI — Writing Intelligence Platform Seven engines, one writing assistant.

ParaFlow AI is a full-stack writing-intelligence SaaS: a Next.js frontend, a FastAPI backend, and seven prompt-engineered/rule-based AI writing tools (paraphrase, humanize, detect, grammar, summarize, translate, SEO) processed synchronously per-request through a single Gemini-backed LLM service, with Supabase for auth/persistence and Stripe for billing. (Celery/Redis are configured in the repo but not currently wired into any live endpoint — see the architecture notes below.)

---

🌍 What It Does

Most writing tools do one thing. ParaFlow AI bundles the full workflow — rewrite it, humanize it, check if it reads as AI-written, fix the grammar, summarize it, translate it, optimize it for SEO — behind one API, with a per-user "Writing DNA" style profile and a multi-agent "Agent Studio" that iteratively revises text until it hits a target quality score.

---

⚡ Architecture (as actually wired up)

                    Client Layer
              ┌────────────────────┐
              │   Next.js 15 Web    │
              │   (React 19 / TS)   │
              └──────────┬─────────┘
                          ▼
              ┌────────────────────┐
              │  Cloudflare CDN /   │   Security & delivery
              │  WAF                │
              └──────────┬─────────┘
                          ▼
              ┌────────────────────┐
              │  FastAPI  /api/v1   │   API gateway + routing
              └──────────┬─────────┘
                          ▼
   ┌──────────────────────────────────────────────────┐
   │  Backend Endpoints                                 │
   │  auth · users · billing · health · tools ·         │
   │  writing_dna · agents                              │
   └──────────────────────┬─────────────────────────────┘
                          ▼
   ┌──────────────────────────────────────────────────┐
   │  AI Orchestration                                  │
   │  llm_service.generate_dict()                       │
   │       → provider factory → GeminiProvider          │
   │  (called synchronously, in-request — see note)    │
   └──────────────────────┬─────────────────────────────┘
                          ▼
   ┌──────────────────────────────────────────────────┐
   │  AI Engines (7)                                    │
   │  Paraphrase · Humanize · Detect · Grammar ·        │
   │  Summarize · Translate · SEO                       │
   └──────────────────────┬─────────────────────────────┘
                          ▼
              ┌────────────────────┐
              │  Supabase (client   │   real path: credits, users,
              │  library, not ORM)  │   writing_dna_profiles, etc.
              └────────────────────┘

Note on the whiteboard version: the original hand-drawn diagram sketches a Mobile/Web/Desktop client layer, a "Gen AI Voice" engine, a separate Vector DB, and a "Mem0" memory feeding a "DNA Engine." In the current codebase: only the Next.js web client is implemented; there's no voice/audio engine; and there's no separate vector database or Mem0 — the closest thing to the "DNA Engine" is Writing DNA (see below).

Note on the Celery/Redis queue: docker-compose.yml runs a Redis container and a celery_worker service, and workers/celery_app.py defines paraphrase_task, humanize_task, detect_task, and agent_studio_task. However, nothing in the live API code calls .delay() or .apply_async() on any of these tasks — every /tools endpoint (tools.py) runs its engine directly and synchronously inside the request handler and returns the result immediately. The Celery tasks would also currently fail if invoked: they import async_session_maker from app.db.database, but that module only defines a stub get_db() that yields None and a no-op init_db() — there is no real SQLAlchemy engine or session factory wired up anywhere in the codebase, despite sqlalchemy[asyncio] and asyncpg being in requirements.txt. The actual, working persistence path for users/credits/writing-DNA is the Supabase Python client (db/supabase.py), called directly from the services.

---

🧠 Core Components

🎨 Frontend — frontend/

• Next.js 15 (App Router) + React 19 + TypeScript
• Tailwind CSS 4 + shadcn/ui (built on Radix primitives)
• Zustand for local state, TanStack Query v5 for server state
• Supabase JS/SSR client for auth
• React Hook Form + Zod for forms/validation, Framer Motion for animation, Recharts for charts
• Feature panels: SummarizerPanel, TranslatorPanel, WritingDNAPanel, etc.

⚙️ Backend — backend/app/

• FastAPI + Pydantic 2 + pydantic-settings
• python-jose + passlib[bcrypt] for JWT access/refresh-token auth
• Real persistence goes through the Supabase Python client (db/supabase.py) — sqlalchemy[asyncio]/asyncpg are in requirements.txt but the app's actual DB dependency (db/database.py) is a stub, so no ORM session is wired up in this snapshot
• Celery 5.4 + Redis are configured (see architecture note above) but no live endpoint currently enqueues a task
• structlog for structured logging, httpx for outbound calls

🧭 AI Orchestration — backend/app/ai/

• llm_service.py — single provider-agnostic entry point for LLM-backed engines
• providers/factory.py — provider abstraction; Gemini is currently the only active provider (gemini-2.5-flash by default), with automatic fallback-chain plumbing in place for future providers
• Not every engine calls the LLM — see the table below. The ones that do build their own system/user prompt; there's no fine-tuning anywhere

🛠️ AI Engines — backend/app/ai/engines/

Engine	File	How it works
Paraphrase	paraphrase_engine.py	Gemini (prompt-engineered rewrite by mode/strength)
Humanize	humanize_engine.py	Gemini (rewrite toward a target AI-detection pass rate)
Grammar	grammar_engine.py	Gemini (grammar/style correction)
Summarize	summarize_engine.py	Gemini (condense text)
Translate	translate_engine.py	Gemini (language translation)
Detect	detect_engine.py	Rule-based, no LLM call — weighted heuristic score from sentence-length uniformity ("perplexity"), variance ("burstiness"), and AI-phrase pattern matching
SEO	seo_engine.py	Rule-based, no LLM call — keyword density, readability, and title-quality heuristics

🧬 Writing DNA — services/writing_dna_service.py

Builds a per-user style profile from writing samples. Two versions of this schema exist in the repo and disagree with each other: the Pydantic model in models/models.py defines style_embedding, vocabulary_richness, formality_score, burstiness_score, rhythm_score, structure_score, etc., while the actual writing_dna_profiles table in supabase_migration.sql has profile_data JSONB, dominant_style, tone_analysis JSONB, vocabulary_score, sentence_variation_score, and readability_score — no style_embedding column at all. Whichever code path runs against the live Supabase table would need to use the SQL migration's column names.

🤖 Agent Studio — services/agent_studio_service.py

Runs a multi-agent revision loop over up to 5 named agents (grammar, seo, humanizer, tone, fact_checker), iterating until a target health score is hit or max_iterations is reached. In the current code, grammar calls GrammarEngine, seo calls SEOEngine, and humanizer calls HumanizeEngine — tone and fact_checker are no-op stubs that report success without changing the text. Scoring between iterations also comes from HealthScoreService.calculate_score() fed with hardcoded inputs rather than a live re-analysis of the text.

📊 Health Score — services/health_score_service.py

A weighted composite score (grammar 25% · readability 20% · originality 20% · human-likeness 20% · SEO 10% · tone 5%) exposed via /api/v1/health/score and /api/v1/health/evolution/{job_id}. Note: this is distinct from the plain /api/health liveness check in main.py, and in the current code both health/score and health/evolution return illustrative/hardcoded values rather than a live computation — consistent with DEMO_MODE=True in core/config.py, which also lets auth, billing, and writing_dna run without a live Supabase connection for local dev/demos.

💳 Billing & Access

• Stripe integration (billing_service.py), real reads/writes go through the Supabase client against the credits table
• Tier naming is inconsistent across the codebase: the Pydantic SubscriptionTier enum (models/models.py) says Free / Pro / Team, but the subscriptions.plan and users.role check constraints in supabase_migration.sql only allow free / pro / enterprise
• ToolJob (queued → processing → completed/failed) exists as a Pydantic model and a tool_jobs table, but the live /tools endpoints don't create or update these rows — they generate a fresh job_id per response and return the result directly without persisting a job record

🗄️ Data — Supabase

Tables (per supabase_migration.sql): users, credits, tool_jobs, writing_dna_profiles, subscriptions, api_keys — one relational Postgres instance behind Supabase, accessed via the Supabase client library rather than SQLAlchemy. No separate vector database.

---

🚀 Quick Start

Backend

cd backend
python -m venv venv
source venv/bin/activate   # venv\Scripts\activate on Windows
pip install -r requirements.txt
uvicorn app.main:app --reload

Frontend

cd frontend
npm install
npm run dev

Full stack (Docker)

docker-compose up --build

Spins up Postgres, Redis, the FastAPI backend, and a celery_worker service — note the worker currently has no task producer feeding it (see the architecture note above), so it will sit idle even when running.

Environment

Copy .env.example → .env in both backend/ and frontend/ and set at minimum: SUPABASE_URL, SUPABASE_KEY, SUPABASE_SERVICE_KEY, GEMINI_API_KEY, plus CELERY_BROKER_URL / CELERY_RESULT_BACKEND (Redis).

---

🗂️ Project Structure

Paraflow-AI-main/
│
├── frontend/                       ← Next.js 15 app
│   └── src/
│       ├── components/features/    ← SummarizerPanel, TranslatorPanel, WritingDNAPanel...
│       ├── components/ui/          ← shadcn/ui components
│       ├── providers/, stores/, hooks/, lib/
│
├── backend/
│   └── app/
│       ├── ai/
│       │   ├── llm_service.py
│       │   ├── providers/          ← factory.py, base.py, gemini.py
│       │   └── engines/            ← paraphrase, humanize, detect, grammar,
│       │                              summarize, translate, seo
│       ├── services/                ← tool, writing_dna, billing,
│       │                              health_score, agent_studio, user
│       ├── api/v1/endpoints/        ← auth, users, billing, health, tools,
│       │                              writing_dna, agents
│       ├── models/, schemas/, db/, workers/, core/
│
├── scripts/                        ← test_all_endpoints.py, test_nvidia.py
├── tests/
├── docker-compose.yml
└── supabase_migration.sql

---

📦 Key Dependencies

Backend (backend/requirements.txt)

fastapi>=0.115.0
uvicorn[standard]>=0.30.0
pydantic>=2.9.0
pydantic-settings>=2.5.0
sqlalchemy[asyncio]>=2.0.0
asyncpg>=0.29.0
python-jose[cryptography]>=3.3.0
passlib[bcrypt]>=1.7.4
httpx>=0.27.0
celery[redis]>=5.4.0
structlog>=24.4.0
supabase>=2.31.0

(sqlalchemy[asyncio]/asyncpg are listed but there's no wired-up engine or session factory in this snapshot — see the architecture notes above. anthropic and openai are also listed but currently unused — Gemini is the only wired-up LLM provider.)

Frontend (frontend/package.json)

next@15.5
react@19
typescript@5.6
tailwindcss@4
zustand@5
@tanstack/react-query@5
@supabase/supabase-js
framer-motion
recharts
react-hook-form + zod

---

📄 Citation

@misc{paraflowai2026,
  title  = {ParaFlow AI: A Full-Stack Writing Intelligence Platform},
  author = {Mantasha},
  year   = {2026},
  url    = {https://github.com/itimantasha/Paraflow-AI},
  note   = {B.Tech Portfolio Project}
}

---

Built with ✍️ by Mantasha & Team

B.Tech · Full-Stack & AI Engineering

⭐ Star this repo if you found it useful