# deep-think-project/server architecture

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

- Interactive diagram: https://gitdiagram.com/deep-think-project/server
- Repository: https://github.com/deep-think-project/server

## Overview

##### Project type and purpose
- This is a full-stack (API-only) web service built with Django.
- Purpose: ingest raw text or URL, classify each sentence as “clear” or “ambiguous” via OpenAI GPT, enrich ambiguous sentences using Perplexity Sonar, then return a detailed JSON response.

##### File structure
- Top-level:
- deepthink_server/ (Django project folder)
– deepthink_server/ (settings, URLs, ASGI/WGSI entry points)
– main_app/ (core business logic: views, utils, models, URL routing, system prompts)
– output/ (six subfolders for intermediate debug files)
– manage.py
- requirements.txt, example.json, README.md
- Key patterns: layered MVC (Django), pipeline stages (raw → indexed → GPT → Sonar → merged)

##### README for insights
- Describes API endpoint, input/output JSON schema
- Lists tech stack: Django, requests + BeautifulSoup (web scraping), spaCy (nlp), openai, dotenv
- Notes debug files under output/1-raw … output/6-merge_gpt_sonar

##### Main components
a. External clients
- Web or script POST → Django API
b. Django API Layer
- ASGI/WGSI server (uvicorn/gunicorn)
- URL router → main_app.views.analyze()
c. Pre-processing
- Input handler (URL fetch via requests + BeautifulSoup)
- spaCy pipeline (ko_core_news_sm) for sentence segmentation
d. AI services
- OpenAI GPT API → Classify sentences
- Perplexity Sonar API → Fetch supporting references
e. Merge & Response
- utils.merge_gpt_and_sonar()
- JSON serializer → HTTP response
f. Debug storage
- output/1-raw, 2-indexed, 3-first_gpt_output, 4-for_sonar, 5-sonar_output, 6-merge_gpt_sonar

##### Relationships & data flow
1. Client → HTTP POST → Django ASGI
2. Django view calls Input Handler
3. If URL: requests → BeautifulSoup → raw text → spaCy
4. spaCy → list of sentences → for-loop
5. Sentence → OpenAI GPT API → returns classification & reason
6. Ambiguous sentences → Perplexity Sonar API → returns references
7. utils merges both outputs → final JSON
8. Debug files written at each stage
9. JSON → HTTP response → Client

##### Architectural patterns & principles
- Layered (presentation → application → integration)
- Pipeline stages saved for reproducibility (debug)
- Single-responsibility in utils, views, system_prompt files
- Environment-based config (.env via dotenv)
- Clear separation of external (AI services) vs. internal components

## Diagram (Mermaid)

```mermaid
graph TB
    %% Clients
    Client["Client (Browser/Script)"]:::external

    %% Core Service
    subgraph "Core Service"
        direction TB
        DjangoASGI["Django ASGI Server"]:::internal
        RouterProject["Project URLs Router"]:::internal
        RouterApp["App URLs Router"]:::internal
        AnalyzeView["analyze() API View"]:::internal
        InputHandler["Input Handler\n(requests + BeautifulSoup)"]:::internal
        Splitter["Sentence Splitter\n(spaCy)"]:::internal
        Merger["Merger & Serializer"]:::internal
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GPT["OpenAI GPT API"]:::external
        Sonar["Perplexity Sonar API"]:::external
    end

    %% Debug Storage
    subgraph "Debug Storage"
        direction TB
        RAW["1-raw"]:::storage
        INDEXED["2-indexed"]:::storage
        FIRSTGPT["3-first_gpt_output"]:::storage
        FORSONAR["4-for_sonar"]:::storage
        SONAROUT["5-sonar_output"]:::storage
        MERGEOUT["6-merge_gpt_sonar"]:::storage
    end

    %% Data Flow
    Client -->|"POST input JSON"| DjangoASGI
    DjangoASGI --> RouterProject
    RouterProject --> RouterApp
    RouterApp --> AnalyzeView
    AnalyzeView -->|"invoke input handling"| InputHandler
    InputHandler -->|"save raw text"| RAW
    InputHandler -->|"raw text"| Splitter
    Splitter -->|"save indexed sentences"| INDEXED
    Splitter -->|"sentence text"| GPT
    GPT -->|"classification"| FIRSTGPT
    GPT -->|"classification"| Merger
    Splitter -->|"ambiguous sentences"| Sonar
    Splitter -->|"debug for sonar"| FORSONAR
    Sonar -->|"references"| SONAROUT
    Sonar -->|"references"| Merger
    Merger -->|"save merged output"| MERGEOUT
    Merger -->|"response JSON"| Client

    %% Click Events
    click DjangoASGI "https://github.com/deep-think-project/server/blob/main/deepthink_server/deepthink_server/asgi.py"
    click RouterProject "https://github.com/deep-think-project/server/blob/main/deepthink_server/deepthink_server/urls.py"
    click RouterApp "https://github.com/deep-think-project/server/blob/main/deepthink_server/main_app/urls.py"
    click AnalyzeView "https://github.com/deep-think-project/server/blob/main/deepthink_server/main_app/views.py"
    click InputHandler "https://github.com/deep-think-project/server/blob/main/deepthink_server/main_app/utils.py"
    click Splitter "https://github.com/deep-think-project/server/blob/main/deepthink_server/main_app/utils.py"
    click Merger "https://github.com/deep-think-project/server/blob/main/deepthink_server/main_app/utils.py"
    click RAW "https://github.com/deep-think-project/server/tree/main/deepthink_server/output/1-raw"
    click INDEXED "https://github.com/deep-think-project/server/tree/main/deepthink_server/output/2-indexed"
    click FIRSTGPT "https://github.com/deep-think-project/server/tree/main/deepthink_server/output/3-first_gpt_output"
    click FORSONAR "https://github.com/deep-think-project/server/tree/main/deepthink_server/output/4-for_sonar"
    click SONAROUT "https://github.com/deep-think-project/server/tree/main/deepthink_server/output/5-sonar_output"
    click MERGEOUT "https://github.com/deep-think-project/server/tree/main/deepthink_server/output/6-merge_gpt_sonar"

    %% Styles
    classDef internal fill:#e0ffe0,stroke:#2d662d,color:#000;
    classDef external fill:#e0e0ff,stroke:#2d2d66,color:#000;
    classDef storage fill:#f0f0f0,stroke:#666666,color:#000
```
