# ashmitmehta2004/smca architecture

> Architecture diagram of the GitHub repository ashmitmehta2004/smca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashmitmehta2004/smca
- Repository: https://github.com/ashmitmehta2004/smca

## Overview

##### What this project is (type + purpose)
This is a **single-service FastAPI web application** that serves:
- A **minimal browser UI** (HTML template + static JS/CSS)
- A **JSON API** endpoint that accepts **PDF/image uploads**, performs **text extraction** (PDF parsing or OCR), runs **heuristic content analysis**, and returns **suggestions + stats**.

##### What the file tree implies about architecture
From the tree:

- `app/main.py`: FastAPI app entrypoint; defines routes (very likely `/` and `/api/analyze`)
- `app/templates/index.html`: server-rendered initial UI page (Jinja2 or similar templating)
- `app/static/app.js`, `styles.css`: client-side behavior + UI styling (file upload, calling API, rendering results)
- `app/services/extract.py`: extraction layer (PDF via `pdfplumber`, image OCR via `pytesseract` + `Pillow`)
- `app/services/analyze.py`: analysis layer (rules/heuristics for engagement suggestions)
- `Dockerfile`: container runtime (includes system deps like Tesseract)
- `requirements.txt`: Python deps (FastAPI, uvicorn, pdfplumber, pytesseract, Pillow, etc.)

Architecturally this is a **layered module structure** inside one process:
**Web/UI layer → API layer → service layer (extract/analyze) → OS-level tools/libs**.

No database, queue, or multi-service separation is indicated.

##### What the README adds (runtime + flow)
The README describes the primary request flow clearly:

##### Extraction
- PDF: `pdfplumber` reads pages and preserves line breaks
- Image: `pytesseract` (Tesseract OCR) + Pillow
##### UI JS renders results + handles loading/error

Deployment: Docker image includes Tesseract; live on Render (container platform).

Shows: Browser ↔ FastAPI container ↔ external tooling (Tesseract) and libraries. Emphasize deployment boundary (Docker/Render).

Shows: Routes/controllers, templates/static serving, extract service, analyze service, temp file handling, and data objects (text, stats, suggestions).

This project benefits from both because it’s “one service” but has meaningful internal pipeline stages.

##### Main components to include (separate into as many as practical)
**Client side (Browser)**
- `index.html` (rendered page)
- `app.js` (upload + fetch `/api/analyze`, render JSON)
- `styles.css`

**Server side (FastAPI app in `app/main.py`)**
- Route: `GET /` (serves UI via `templates/index.html`)
- Route: `POST /api/analyze` (multipart upload handler, orchestrates pipeline)
- Static files handler (serves `/static/app.js`, `/static/styles.css`)

**Service layer (`app/services`)**
- `extract.py`
- PDF extraction subcomponent: `pdfplumber`
- Image OCR subcomponent: `pytesseract` + Pillow
- Normalization step (whitespace cleanup)
- `analyze.py`
- Stats calculator (word count, hashtags, punctuation, etc.)
- Suggestion rules engine (deterministic heuristics)

**Runtime/External dependencies**
- OS temp filesystem (where uploads are written)
- Tesseract binary (external executable invoked by `pytesseract`)
- (Optional to show) Render.com hosting as “Deployment environment”

- Uploaded file (PDF/Image)
- Temp file path
- Raw extracted text
- Normalized text
- Analysis result JSON (stats + suggestions)

##### Browser → FastAPI `GET /`
Payload: HTTP request; Response: HTML (template)
##### Browser → FastAPI static
Payload: GET `/static/app.js`, `/static/styles.css`
##### Browser (app.js) → FastAPI `POST /api/analyze`
Payload: `multipart/form-data` (file)
##### FastAPI handler → Temp File System
Payload: write uploaded bytes to temp path
##### FastAPI handler → `extract.py`
Payload: temp path + file type
##### `extract.py` → `pdfplumber` (if PDF)
Payload: PDF path; Response: page text
##### `extract.py` → `pytesseract`/Pillow → Tesseract (if image)
Payload: image bytes/path; Response: OCR text
##### `extract.py` → FastAPI handler
Payload: raw/normalized text
##### FastAPI handler → `analyze.py`
Payload: normalized text
##### `analyze.py` → FastAPI handler
Payload: stats + suggestions object
##### FastAPI handler → Browser
Payload: JSON response
##### Browser (app.js) → DOM
Payload: render results; show loading/errors

- FastAPI + Uvicorn (web server)
- Jinja2/templates (implied by `templates/` usage; if confirmed in code, label it)
- pdfplumber (PDF text)
- Pillow + pytesseract (image OCR)
- Tesseract OCR (system binary)
- Docker (containerization)
- Render.com (hosting target; optional but useful for “live URL” context)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========== External / Client ==========
    subgraph "Client (Browser)"
        BROWSER["Web Browser"]:::client
        DOM["DOM Renderer"]:::client

        subgraph "UI Assets"
            HTML["index.html (Template Render)"]:::frontend
            JS["app.js (Upload + Fetch + Render)"]:::frontend
            CSS["styles.css"]:::frontend
        end
    end

    %% ========== Deployment / Container ==========
    subgraph "Deployment Environment (Render.com)"
        subgraph "Docker Container (FastAPI + Uvicorn)"
            UV["Uvicorn ASGI Server"]:::runtime
            APP["FastAPI App"]:::runtime

            subgraph "Web Layer (Routes + Static)"
                R_ROOT["GET / (Serve UI)"]:::api
                R_STATIC["Static Files Mount (/static/*)"]:::api
                R_ANALYZE["POST /api/analyze (Upload Handler)"]:::api
            end

            subgraph "Service Layer (app/services)"
                EXTRACT["extract.py (Extract + Normalize)"]:::service
                subgraph "Extraction Strategy (by file type)"
                    EX_PDF["PDF Extraction (pdfplumber)"]:::service
                    EX_IMG["Image OCR (Pillow + pytesseract)"]:::service
                    NORMALIZE["Text Normalization"]:::service
                end

                ANALYZE["analyze.py (Stats + Suggestions)"]:::service
                STATS["Stats Calculator"]:::service
                RULES["Heuristic Rules Engine"]:::service
            end

            TEMPFS[("Temp Filesystem (/tmp)")]:::storage
        end

        subgraph "External Dependencies"
            PDFPLUMBER["pdfplumber (Python lib)"]:::lib
            PILLOW["Pillow (Python lib)"]:::lib
            PYTESS["pytesseract (Python wrapper)"]:::lib
            TESS["Tesseract OCR (System binary)"]:::external
        end
    end

    %% ========== Repo / Build Artifacts ==========
    subgraph "Build & Docs"
        DOCKER["Dockerfile"]:::build
        REQS["requirements.txt"]:::build
        README["README.md"]:::docs
    end

    %% ========== Relationships (Vertical, Pipeline-style) ==========
    BROWSER -->|"HTTP GET /"| R_ROOT
    R_ROOT -->|"render_template()"| HTML
    HTML -->|"HTML response"| BROWSER

    BROWSER -->|"HTTP GET /static/app.js"| R_STATIC
    R_STATIC -->|"serve"| JS
    JS -->|"JS asset"| BROWSER

    BROWSER -->|"HTTP GET /static/styles.css"| R_STATIC
    R_STATIC -->|"serve"| CSS
    CSS -->|"CSS asset"| BROWSER

    JS -->|"user_selects_file"| DOM
    JS -->|"HTTP POST /api/analyze (multipart/form-data)"| R_ANALYZE

    R_ANALYZE -->|"write_upload_bytes"| TEMPFS
    TEMPFS -->|"temp_file_path"| R_ANALYZE

    R_ANALYZE -->|"dispatch(file_type, temp_path)"| EXTRACT
    EXTRACT -->|"if_PDF"| EX_PDF
    EXTRACT -->|"if_Image"| EX_IMG

    EX_PDF -->|"read_PDF_pages(path)"| PDFPLUMBER
    PDFPLUMBER -->|"raw_text_with_linebreaks"| EX_PDF
    EX_PDF -->|"raw_text"| NORMALIZE

    EX_IMG -->|"open_image(path)"| PILLOW
    PILLOW -->|"image_object"| EX_IMG
    EX_IMG -->|"ocr(image)"| PYTESS
    PYTESS -->|"invoke_OCR"| TESS
    TESS -->|"OCR_text"| PYTESS
    PYTESS -->|"raw_text"| EX_IMG
    EX_IMG -->|"raw_text"| NORMALIZE

    NORMALIZE -->|"normalized_text"| EXTRACT
    EXTRACT -->|"normalized_text"| R_ANALYZE

    R_ANALYZE -->|"analyze(text)"| ANALYZE
    ANALYZE -->|"compute"| STATS
    ANALYZE -->|"apply_rules"| RULES
    STATS -->|"stats_object"| ANALYZE
    RULES -->|"suggestions_list"| ANALYZE
    ANALYZE -->|"result(stats+suggestions)"| R_ANALYZE

    R_ANALYZE -->|"JSON response"| JS
    JS -->|"render_results/loading/errors"| DOM

    %% Server wiring
    UV -->|"ASGI"| APP
    APP -->|"routes"| R_ROOT
    APP -->|"static_mount"| R_STATIC
    APP -->|"routes"| R_ANALYZE

    %% Build/Docs relationships
    DOCKER -->|"packages_system_deps(e.g.,tesseract)"| TESS
    REQS -->|"pins_python_deps"| APP
    README -->|"documents_request_flow"| R_ANALYZE

    %% ========== Click Events (component_mapping paths only) ==========
    click APP "https://github.com/ashmitmehta2004/smca/blob/main/app/main.py"
    click R_ROOT "https://github.com/ashmitmehta2004/smca/blob/main/app/main.py"
    click R_STATIC "https://github.com/ashmitmehta2004/smca/blob/main/app/main.py"
    click R_ANALYZE "https://github.com/ashmitmehta2004/smca/blob/main/app/main.py"

    click HTML "https://github.com/ashmitmehta2004/smca/blob/main/app/templates/index.html"
    click JS "https://github.com/ashmitmehta2004/smca/blob/main/app/static/app.js"
    click CSS "https://github.com/ashmitmehta2004/smca/blob/main/app/static/styles.css"

    click EXTRACT "https://github.com/ashmitmehta2004/smca/blob/main/app/services/extract.py"
    click ANALYZE "https://github.com/ashmitmehta2004/smca/blob/main/app/services/analyze.py"
    click STATS "https://github.com/ashmitmehta2004/smca/blob/main/app/services/analyze.py"
    click RULES "https://github.com/ashmitmehta2004/smca/blob/main/app/services/analyze.py"
    click EX_PDF "https://github.com/ashmitmehta2004/smca/blob/main/app/services/extract.py"
    click EX_IMG "https://github.com/ashmitmehta2004/smca/blob/main/app/services/extract.py"
    click NORMALIZE "https://github.com/ashmitmehta2004/smca/blob/main/app/services/extract.py"

    click DOCKER "https://github.com/ashmitmehta2004/smca/tree/main/Dockerfile"
    click REQS "https://github.com/ashmitmehta2004/smca/blob/main/requirements.txt"
    click README "https://github.com/ashmitmehta2004/smca/blob/main/README.md"

    %% Directory click (service package)
    click UV "https://github.com/ashmitmehta2004/smca/tree/main/app/services/"
    click PDFPLUMBER "https://github.com/ashmitmehta2004/smca/blob/main/requirements.txt"
    click PILLOW "https://github.com/ashmitmehta2004/smca/blob/main/requirements.txt"
    click PYTESS "https://github.com/ashmitmehta2004/smca/blob/main/requirements.txt"

    %% ========== Styles ==========
    classDef client fill:#dbeafe,stroke:#1e40af,stroke-width:1px,color:#0b1b3a
    classDef frontend fill:#bfdbfe,stroke:#1d4ed8,stroke-width:1px,color:#0b1b3a
    classDef runtime fill:#93c5fd,stroke:#1d4ed8,stroke-width:1px,color:#0b1b3a
    classDef api fill:#60a5fa,stroke:#1d4ed8,stroke-width:1px,color:#061a33
    classDef service fill:#bbf7d0,stroke:#166534,stroke-width:1px,color:#052e16
    classDef lib fill:#fed7aa,stroke:#9a3412,stroke-width:1px,color:#3b1605
    classDef external fill:#fecaca,stroke:#991b1b,stroke-width:2px,color:#3b0a0a
    classDef storage fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#111827
    classDef build fill:#fde68a,stroke:#a16207,stroke-width:1px,color:#2a1a05
    classDef docs fill:#fce7f3,stroke:#9d174d,stroke-width:1px,color:#3b0a22
```
