# mplacona/threadscout architecture

> Architecture diagram of the GitHub repository mplacona/threadscout, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mplacona/threadscout
- Repository: https://github.com/mplacona/threadscout

## Overview

##### Project type and purpose
- ThreadScout is a full-stack web application whose goal is to help users discover high-intent Reddit threads, summarize subreddit rules, score opportunities, draft reply variants, and track outcomes.
- The README confirms a React+Vite frontend, a Hono-based Node/TypeScript backend, serverless “tools” functions, and pluggable storage (DO Spaces vs. local JSON).

##### File structure
- Top-level directories:
- src/ – React SPA (TSX components, pages, hooks, utils)
- server/ – Hono HTTP server (routes, schemas, services, utils)
- functions/tools/ – Standalone serverless helpers (fetch-rules, validate-links)
- public/ – Static assets (favicon, robots.txt)
- scripts/ – Build scripts for server and functions
- Config files: vite.config.ts, tsconfig*, postcss.config.js, bun.lockb / package.json, project.yml, .env.example
- Storage abstraction: server/services/storage.ts chooses DigitalOcean Spaces in prod or local JSON under /data in dev.
- External integrations: Reddit API, Gradient AI agent, link-allowlist enforcement.

##### README for additional insights
- It already outlines a two-tier architecture: Frontend (Route: Dashboard, Thread) and Backend (Hono server with storage abstraction, redditClient, agentClient, validators).
- It references serverless tools for rule fetching and link validation—these are likely deployed as edge functions or lambdas.

a. Main components
1) User’s Browser running React SPA (Vite)
2) Hono API Server (Node/TypeScript)
3) Serverless Tools Functions (fetch-rules, validate-links)
4) Storage Layer (DigitalOcean Spaces or local JSON files)
5) External Services
– Reddit API (OAuth + public JSON)
– Gradient AI Agent
b. Relationships & Data flows
- Browser → HTTP(S) → Hono API (routes: /scan, /outcomes, /tools, /streamScan, etc.)
- Hono API → Storage Service → (DO Spaces or local FS)
- Hono API → redditClient → Reddit API
- Hono API → agentClient → Gradient AI
- Hono API → validator tools or calls out to the serverless tools endpoints
- Optional: Browser directly loads static index.html + assets from public/
c. Architectural patterns & design principles
– Single-Page Application (SPA) + REST / streaming API
– Storage Abstraction pattern (Strategy) for dev vs. prod
– Micro-services / serverless for specialized tasks (rules fetch, link validation)
– Layered services: routes → schemas → services → utils
d. Key technologies & frameworks
– Frontend: Vite, React, TypeScript, Tailwind CSS, shadcn/ui
– Backend: Hono (TypeScript), Node.js
– Serverless: Netlify/AWS Lambda style functions in functions/tools
– Storage: DigitalOcean Spaces or local JSON
– Testing: Vitest
– Deployment: Static build + Node server

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React+Vite)"
        direction TB
        ReactSPA["React SPA (Vite, TSX)"]:::frontend
        APIWrapper["API Wrapper & Clients"]:::frontend
    end

    %% Backend Layer
    subgraph "Hono API Server (Node/TS)"
        direction TB
        APIServer["Hono API Server\n(server/index.ts)"]:::backend
        subgraph "Routes"
            direction TB
            RoutesDir["Routes (scan, outcomes, streamScan, subreddits, threads, tools)"]:::backend
        end
        subgraph "Schemas"
            direction TB
            SchemasDir["Schemas (thread.ts, outcomes.ts, draft.ts)"]:::backend
        end
        subgraph "Services"
            direction TB
            ServicesDir["Services"]:::backend
            RedditClient["redditClient"]:::backend
            AgentClient["agentClient"]:::backend
            RulesCache["rulesCache"]:::backend
            Validators["validators"]:::backend
            StorageService["storage.ts (abstraction)"]:::backend
        end
        subgraph "Utils"
            direction TB
            UtilsDir["Utils (logger, startup-banner)"]:::backend
        end
    end

    %% Storage Abstraction Branch
    subgraph "Storage Layer" 
        direction TB
        StorageCylinder[(Storage)]:::storage
        DOspaces["DigitalOcean Spaces"]:::storage
        LocalJSON["Local JSON (dev)"]:::storage
    end

    %% Serverless Tools
    subgraph "Serverless Tools Functions"
        direction TB
        FetchRules["fetch-rules"]:::serverless
        ValidateLinks["validate-links"]:::serverless
    end

    %% External Services
    subgraph "External Services"
        direction TB
        RedditAPI["Reddit API"]:::external
        GradientAI["Gradient AI Agent"]:::external
    end

    %% Build Scripts
    subgraph "Build Scripts"
        direction TB
        BuildServer["build-server.ts"]:::backend
        BuildFunctions["build-functions.ts"]:::serverless
    end

    %% Connections
    ReactSPA -->|"calls REST API"| APIServer
    APIWrapper --> APIServer
    APIServer -->|uses| RoutesDir
    APIServer -->|uses| SchemasDir
    APIServer -->|uses| ServicesDir
    APIServer -->|uses| UtilsDir

    ServicesDir --> RedditClient
    ServicesDir --> AgentClient
    ServicesDir --> RulesCache
    ServicesDir --> Validators
    ServicesDir --> StorageService

    StorageService --> StorageCylinder
    StorageCylinder --> DOspaces
    StorageCylinder --> LocalJSON

    APIServer -->|"fetch rules"| FetchRules
    APIServer -->|"validate links"| ValidateLinks

    APIServer -->|"queries"| RedditAPI
    APIServer -->|"invokes"| GradientAI

    BuildServer --> APIServer
    BuildFunctions --> FetchRules
    BuildFunctions --> ValidateLinks

    %% Click Events - Frontend
    click ReactSPA "https://github.com/mplacona/threadscout/blob/main/src/main.tsx"
    click APIWrapper "https://github.com/mplacona/threadscout/blob/main/src/lib/api.ts"

    %% Click Events - Backend
    click APIServer "https://github.com/mplacona/threadscout/blob/main/server/index.ts"
    click RoutesDir "https://github.com/mplacona/threadscout/tree/main/server/routes/"
    click SchemasDir "https://github.com/mplacona/threadscout/tree/main/server/schemas/"
    click ServicesDir "https://github.com/mplacona/threadscout/tree/main/server/services/"
    click UtilsDir "https://github.com/mplacona/threadscout/tree/main/server/utils/"
    click BuildServer "https://github.com/mplacona/threadscout/blob/main/scripts/build-server.ts"

    %% Click Events - Storage
    click StorageService "https://github.com/mplacona/threadscout/blob/main/server/services/storage.ts"
    click DOspaces "https://github.com/mplacona/threadscout/blob/main/server/services/spacesStorage.ts"
    click LocalJSON "https://github.com/mplacona/threadscout/blob/main/server/services/localStorage.ts"

    %% Click Events - Serverless
    click FetchRules "https://github.com/mplacona/threadscout/blob/main/functions/tools/fetch-rules/index.js"
    click ValidateLinks "https://github.com/mplacona/threadscout/blob/main/functions/tools/validate-links/index.js"
    click BuildFunctions "https://github.com/mplacona/threadscout/blob/main/scripts/build-functions.ts"

    %% Click Events - External Clients in Frontend
    click APIWrapper "https://github.com/mplacona/threadscout/blob/main/src/lib/api.ts"
    click APIWrapper "https://github.com/mplacona/threadscout/blob/main/src/lib/reddit-client.ts"
    click APIWrapper "https://github.com/mplacona/threadscout/blob/main/src/lib/agent-client.ts"
    click APIWrapper "https://github.com/mplacona/threadscout/blob/main/src/lib/linkValidator.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6
    classDef backend fill:#D5F5E3,stroke:#28a745
    classDef serverless fill:#FFE5B4,stroke:#d97706
    classDef storage fill:#E8DAEF,stroke:#6f42c1
    classDef external fill:#E5E7E9,stroke:#6c757d
```
