# mintlify/writer architecture

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

- Interactive diagram: https://gitdiagram.com/mintlify/writer
- Repository: https://github.com/mintlify/writer

## Overview

##### Project type and purpose
- This is a monorepo containing:
- Two IDE extensions (VSCode in TypeScript, IntelliJ in Kotlin/Java)
- A Node.js/TypeScript backend (the “Writer Server”)
- Purpose: Users highlight code in their editor → invoke “Write Docs” → the extension calls the Writer server → generates docstrings via AI/parsing/formatting → returns and inserts documentation.

##### File structure
- Top-level directories:
- `.github` – CI/CD workflows (builds, tests, deploys)
- `intellij` – IntelliJ plugin project (Gradle, Kotlin/Java sources, UI forms)
- `server` – Node.js/TypeScript service (routes, services, models, parsing/formatting, workers)
- `vscode` – VSCode extension (TS code, webpack, tests)
- The server folder contains standard Express-style routes, a Mongoose layer, background workers, and integrations (Stripe, Segment, Translate, OpenAI).

##### README for additional context
- Mintlify Writer generates documentation automatically, supports multiple languages and doc-formats, never stores user code.

a. Main components
- Client Layer (two IDE plugins):
- VSCode Extension (TypeScript)
- IntelliJ Plugin (Kotlin/Java)
- API Gateway / Load Balancer (optional, if deployed behind one)
- Writer Server (Node.js/TypeScript monolith)
- HTTP API (Express-style routes)
- Business Logic / Controllers
- Parsing Module (per-language parsers)
- Formatting Module (docstring formatters)
- Worker Pool (background Codex/inference jobs)
- Data Layer (Mongoose + MongoDB)
- Third-Party Integrations (OpenAI/Codex, Stripe, Segment, Translate API)
- Persistence Layer
- MongoDB (for settings, quotas, progress tracking)
- External Services
- OpenAI API
- Stripe Billing
- Segment Analytics
- Translate (e.g., Google Translate)

b. Relationships & interactions
- User → Trigger “Write Docs” in the IDE
- IDE Extension → HTTP(S) → Writer Server `/writer` route
- Writer Server Controllers → invoke Parsing → Formatting → Worker(s) for heavy AI calls
- Worker → OpenAI API → receives generated docs → returns to Controller
- Controller → persists metadata/usage in MongoDB (via Mongoose)
- Controller → returns generated docstring JSON → IDE Extension
- Extension → injects docstring into user’s code editor
- Billing/Usage tracked via Stripe & Segment calls from the service

c. Architectural patterns & design principles
- Clear separation of concerns:
- Presentation (IDE plugins) vs. API layer vs. business logic vs. data persistence
- Modular parsing/formatting pipeline: per-language parsers and formatters live in distinct folders
- Background workers for long-running AI calls (prevents blocking HTTP threads)
- Monorepo structure to lock dependencies and share configuration/linters/CI

d. Key technologies & frameworks
- IDE Plugins: VSCode API, Webpack, Kotlin/Java Swing UI (IntelliJ)
- Server: Node.js, TypeScript, Express‐style routing, Mongoose, Jest tests
- Deployment: Heroku (Procfile, app.json), GitHub Actions
- External APIs: OpenAI/Codex, Stripe, Segment, Google Translate

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        VSCodeExt["VSCode Extension"]:::frontend
        IntelliJExt["IntelliJ Plugin"]:::frontend
    end

    %% Server Layer
    subgraph "Writer Server"
        direction TB
        HTTPAPI["HTTP API\n(server/routes)"]:::server
        Controllers["Business Logic / Controllers\n(server/routes/writer)"]:::server
        Parsing["Parsing Module\n(server/parsing)"]:::server
        Formatting["Formatting Module\n(server/formatting)"]:::server
        WorkerPool["Worker Pool\n(server/workers)"]:::server
        DataLayer["Mongoose Service\n(server/services/mongoose.ts)"]:::server
        Integrations["Third-Party Integrations"]:::server
    end

    %% Persistence Layer
    subgraph "Persistence"
        direction TB
        MongoDB["MongoDB"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        Stripe["Stripe Billing"]:::external
        Segment["Segment Analytics"]:::external
        Translate["Translate API"]:::external
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        GitHubA["GitHub Actions\n(.github/workflows)"]:::ci
        Heroku["Heroku Config\n(server/Procfile)"]:::ci
        Monorepo["Monorepo Tooling\n(package.json)"]:::ci
    end

    %% Connections
    VSCodeExt -->|"POST /writer/generate\nHTTPS JSON"| HTTPAPI
    IntelliJExt -->|"POST /writer/generate\nHTTPS JSON"| HTTPAPI

    HTTPAPI -->|"invoke controller"| Controllers
    Controllers -->|"parse code"| Parsing
    Parsing -->|"format AST"| Formatting
    Controllers -->|"enqueue job"| WorkerPool
    WorkerPool -->|"call AI"| OpenAI
    WorkerPool -->|"return docs"| Controllers
    Controllers -->|"persist metadata"| DataLayer
    DataLayer -->|"(reads/writes)"| MongoDB
    Controllers -->|"return doc JSON"| VSCodeExt
    Controllers -->|"return doc JSON"| IntelliJExt

    %% Analytics & Billing
    Controllers -.->|"Segment.track()"| Segment
    Controllers -.->|"Stripe.billing"| Stripe
    Controllers -.->|"Translate.request"| Translate

    %% CI/CD Flows
    Monorepo --> GitHubA
    GitHubA --> Heroku

    %% Click Events
    click VSCodeExt "https://github.com/mintlify/writer/blob/master/vscode/src/extension.ts"
    click IntelliJExt "https://github.com/mintlify/writer/tree/master/intellij/src/main"
    click HTTPAPI "https://github.com/mintlify/writer/tree/master/server/routes"
    click Controllers "https://github.com/mintlify/writer/blob/master/server/routes/writer/index.ts"
    click Parsing "https://github.com/mintlify/writer/blob/master/server/parsing/index.ts"
    click Formatting "https://github.com/mintlify/writer/blob/master/server/formatting/functions.ts"
    click WorkerPool "https://github.com/mintlify/writer/blob/master/server/workers/index.ts"
    click DataLayer "https://github.com/mintlify/writer/blob/master/server/services/mongoose.ts"
    click OpenAI "https://github.com/mintlify/writer/blob/master/server/brain/codex/docs.ts"
    click Stripe "https://github.com/mintlify/writer/blob/master/server/services/stripe.ts"
    click Segment "https://github.com/mintlify/writer/blob/master/server/services/segment.ts"
    click Translate "https://github.com/mintlify/writer/blob/master/server/services/translate.ts"
    click GitHubA "https://github.com/mintlify/writer/tree/master/.github/workflows"
    click Heroku "https://github.com/mintlify/writer/tree/master/server/Procfile"
    click Monorepo "https://github.com/mintlify/writer/blob/master/package.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#66b0ff
    classDef server fill:#d4edda,stroke:#28a745
    classDef database fill:#f8f9fa,stroke:#6c757d,stroke-dasharray: 5 5
    classDef external fill:#fff3cd,stroke:#ffcd39
    classDef ci fill:#e2e3e5,stroke:#adb5bd,stroke-dasharray: 2 2
```
