Architecture Overview

High-Level Diagram

Something like this

Component Responsibilities

• Next.js

  • Renders pages and components (React server/client).

  • Hosts API routes that either forward file uploads to the Python service or call AI APIs directly.

• Supabase

  • Manages user authentication and sessions.

  • Stores uploaded documents and analysis data in PostgreSQL.

  • Provides object storage for file uploads.

• Python Microservice (FastAPI)

  • Handles .docx/.pdf upload endpoints.

  • Parses document structure, runs checks, and computes scores.

  • Inserts analysis results and paragraphs into Supabase.

• External AI Services

  • Gemini API: Used for advanced content validation and scoring.

  • ElevenLabs API: Generates text-to-speech audio.

  • Winston AI: Performs AI-detection and summarization tasks.

Architectural Decisions

• Separation of Concerns

  • Splitting into Next.js and Python service keeps UI logic (React, routing) separate from heavy document parsing and database writes.

• Supabase as Managed Service

  • Chosen for built-in authentication, storage, and PostgreSQL hosting—minimizes infrastructure overhead.

• Use of FastAPI

  • Lightweight, high-performance framework ideal for parsing and analysis tasks without blocking the frontend.

• Direct AI API Calls vs. Local Models

  • Opted for Gemini, ElevenLabs, and Winston AI to leverage maintained services and avoid on-premise model hosting.

• API Proxying

  • Next.js routes hide service URLs and secrets from the client, centralizing all server-side calls.