# khaja-samiuddin/ai-paper-writer architecture

> Architecture diagram of the GitHub repository khaja-samiuddin/ai-paper-writer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khaja-samiuddin/ai-paper-writer
- Repository: https://github.com/khaja-samiuddin/ai-paper-writer

## Overview

##### Project type and purpose
- This is a stand-alone Python CLI tool (“AI Paper Writer”) that fetches metadata on recent ML papers, applies a multi-factor trending-score algorithm, and calls the OpenAI API to generate a LinkedIn-ready post.
- Not a multi-tier web app; it’s a single process pipeline with external API integrations.

##### File structure
- Top level:
- ai_paper_writer.py – main script containing fetch, scoring, generation logic
- requirements.txt / env.example / .gitignore / LICENSE / README.md
- No separate “src” or “tests” folders, no database, no web server or UI components.
- Uses environment variables (.env) for API keys.

##### Key insights from the README
- External dependencies: Papers-with-Code API, OpenAI API
- Core modules inside the script:
- Fetching recent papers
- Calculating “trending” and “validation” scores
- Selecting top candidate
- Generating summary and “hot takes” with GPT
- Configuration parameters (year filter, scoring weights) are hard-coded or easily tweaked in the script.

##### Detail is key—capture all essential components and flows
- Even though it’s a small script, break down the scoring engine into its two layers.
- Config inputs (year filter, score weights) as parameters.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Configuration and Documentation
    subgraph "Configuration & Docs"
        ConfigLoader["Configuration Loader (.env)"]:::config
        Req["requirements.txt"]:::config
        README["README.md"]:::config
    end

    %% Core Pipeline
    CLI["CLI / Entry Point"]:::config
    Fetcher["Paper Fetcher"]:::internal
    ScoringEngine["Scoring Engine"]:::internal
    SelectionLogic["Selection Logic"]:::internal
    GenerationEngine["Generation Engine"]:::internal
    OutputFormatter["Output Formatter"]:::output
    StdOut["Stdout / File"]:::output

    %% Scoring Subcomponents
    subgraph "Scoring Engine"
        Trending["Trending Score"]:::internal
        Validation["Validation Score"]:::internal
    end

    %% External Services
    PapersAPI["Papers-with-Code API"]:::external
    OpenAIAPI["OpenAI API"]:::external

    %% Pipeline Flow
    ConfigLoader -->|loads .env| CLI
    Req -->|defines deps| CLI
    README -->|provides docs| CLI
    CLI -->|invokes| Fetcher
    Fetcher -->|fetches JSON via HTTP| PapersAPI
    Fetcher -->|returns papers list| ScoringEngine
    ScoringEngine --> Trending
    ScoringEngine --> Validation
    Trending -->|score| SelectionLogic
    Validation -->|score| SelectionLogic
    SelectionLogic -->|selects top paper| GenerationEngine
    GenerationEngine -->|calls GPT| OpenAIAPI
    GenerationEngine -->|returns text| OutputFormatter
    OutputFormatter -->|writes post| StdOut

    %% Click Events
    click CLI "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/ai_paper_writer.py"
    click ConfigLoader "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/env.example"
    click Fetcher "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/ai_paper_writer.py"
    click ScoringEngine "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/ai_paper_writer.py"
    click Trending "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/ai_paper_writer.py"
    click Validation "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/ai_paper_writer.py"
    click SelectionLogic "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/ai_paper_writer.py"
    click GenerationEngine "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/ai_paper_writer.py"
    click OutputFormatter "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/ai_paper_writer.py"
    click Req "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/requirements.txt"
    click README "https://github.com/khaja-samiuddin/ai-paper-writer/blob/main/README.md"

    %% Styles
    classDef internal fill:#a8f3a8,stroke:#333,stroke-width:1px
    classDef config fill:#8ecae6,stroke:#333,stroke-width:1px
    classDef external fill:#f4ac45,stroke:#333,stroke-width:1px
    classDef output fill:#d3d3d3,stroke:#333,stroke-width:1px
```
