# deepl/deepl-mock architecture

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

- Interactive diagram: https://gitdiagram.com/deepl/deepl-mock
- Repository: https://github.com/deepl/deepl-mock

## Overview

Purpose and principal workflow: DeepL API mock server for client-library testing, with a separate basic proxy listener. The main workflow starts when an external API client or test sends an HTTP request: the Express app in `index.js` applies middleware, dispatches versioned API routes, and returns simulated DeepL responses. For text translation, route handling delegates language validation and canned translation behavior to the language subsystem; other routes cover account usage, documents, glossaries, translation memories, and writing features.

Components

**HTTP entry, routes, and proxy**
- **API client or test** — *(external; no repository path)* Initiates the principal workflow by sending HTTP requests to the mock API, as documented in the README.
- **Express API and proxy listeners** — `index.js` Sets up the Express app and API routes, including v2 language, usage, translation, and writing endpoints; the README documents a second port for proxy use. The sampled excerpt does not show listener startup or proxy forwarding details.

**Request context and contract checking**
- **Session middleware and session state** — `sessions.js` Creates in-memory sessions from `mock-server-session` headers, attaches session settings to requests, and supports simulated no-response and proxy-expectation behavior.
- **Authentication and account state** — `auth.js` Extracts an auth key, creates and refreshes in-memory user accounts, and initializes usage limits from session settings.
- **OpenAPI validation** — `response-validator.js` Loads the spec from a configured source and provides request/response validation middleware; the README documents opt-in validation and its startup requirements.
- **HTTP utilities** — `util.js` Supplies shared request/error and cleanup helpers; the sampled session and domain modules use its cleanup scheduling and `HttpError` behavior.

**Simulated API domains**
- **Language and text behavior** — `languages.js` Reads language and product configuration, checks language and feature support, and supplies mock translation, correction, and rephrasing results.
- **Language feature configuration** — `config/languages/language-list.json` Provides language-list data consumed by `languages.js`; additional product configuration files are present in the same directory.
- **Document translation lifecycle** — `documents.js` Stores uploaded document metadata and files, reports queued/translating/completed status, and invokes `languages.translate` to produce output.
- **v2 glossaries** — `glossariesV2.js` Implements in-memory v2 glossary creation, lookup, entry retrieval, and removal, with language-pair validation.
- **v3 glossaries** — `glossariesV3.js` Implements in-memory v3 glossaries and dictionaries, including language-pair checks and entry-format handling.
- **Glossary CSV parsing** — `glossariesCsvParser.js` Converts CSV entries into glossary source/target pairs and rejects invalid or empty input.
- **Translation memories and jobs** — `translationMemories.js` Keeps in-memory translation memories and import/export jobs, with ownership checks and poll-driven job status.
- **Style rules** — `styleRules.js` Manages in-memory style rules and custom instructions, including validation and version updates.

Relationships
- **API client or test -> Express API and proxy listeners**: sends HTTP requests to the documented mock API or proxy ports; README.
- **Express API and proxy listeners -> Session middleware and session state**: API requests use session middleware and session-derived fault settings; `sessions.js` documents middleware behavior, while `index.js` shows route middleware registration.
- **Express API and proxy listeners -> Authentication and account state**: protected routes apply auth middleware before handlers; `index.js` route registrations and `auth.js` middleware.
- **Express API and proxy listeners -> OpenAPI validation**: validation middleware is available for app installation when enabled; README and `response-validator.js`. The sampled excerpts do not establish its exact installation order.
- **Authentication and account state -> Session middleware and session state**: reads session initialization limits when creating user usage state; `auth.js`.
- **Express API and proxy listeners -> Language and text behavior**: translation and writing handlers use language helpers; `index.js` and `languages.js`.
- **Express API and proxy listeners -> Document translation lifecycle**: document API handlers delegate document operations; `index.js` documents route handlers and `documents.js` exports lifecycle operations.
- **Document translation lifecycle -> Language and text behavior**: invokes `languages.translate` to generate document output; `documents.js`.
- **Express API and proxy listeners -> v2 glossaries**: v2 glossary handlers delegate glossary operations; `index.js` glossary handler excerpts and `glossariesV2.js`.
- **Express API and proxy listeners -> v3 glossaries**: v3 glossary handlers delegate glossary operations; `index.js` shows a v3 handler and `glossariesV3.js`.
- **v3 glossaries -> Glossary CSV parsing**: parses CSV dictionary entries during glossary creation; `glossariesV3.js`.
- **Express API and proxy listeners -> Translation memories and jobs**: translation-memory handlers call memory and job operations; `index.js` shows a handler calling `getTranslationMemoryInfo`, and `translationMemories.js`.
- **Express API and proxy listeners -> Style rules**: style-rule handlers call list and mutation operations; `index.js` shows a list call, and `styleRules.js`.

Coverage limits: The `index.js` excerpt omits substantial routing and startup code, so listener construction, proxy forwarding, middleware installation order, and several domain route mappings could not be fully verified. The README documents additional session behavior beyond the sampled session code. No persistence beyond in-memory maps and document files is established by these inputs.

Main entry points: [`index.js`](https://github.com/deepl/deepl-mock/blob/main/index.js) (Express API and Proxy), [`auth.js`](https://github.com/deepl/deepl-mock/blob/main/auth.js) (Authentication and Accounts), [`documents.js`](https://github.com/deepl/deepl-mock/blob/main/documents.js) (Document Translation), [`glossariesV3.js`](https://github.com/deepl/deepl-mock/blob/main/glossariesV3.js) (v3 Glossaries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http_entry["HTTP Entry"]
  node_api_client(("API Client or Test<br/>external"))
  node_express_api["Express API and Proxy<br/>HTTP server"]
end

subgraph group_request_context["Request Context"]
  node_sessions["Session Middleware<br/>[sessions.js]"]
  node_auth["Authentication and Accounts<br/>middleware"]
  node_openapi_validation["OpenAPI Validation<br/>middleware"]
end

subgraph group_translation["Translation Services"]
  node_languages["Language and Text Behavior<br/>[languages.js]"]
  node_documents["Document Translation<br/>[documents.js]"]
end

subgraph group_api_domains["API Domains"]
  node_glossaries_v2["v2 Glossaries<br/>[glossariesV2.js]"]
  node_glossaries_v3["v3 Glossaries<br/>[glossariesV3.js]"]
  node_csv_parser["Glossary CSV Parser"]
  node_translation_memories["Translation Memories and Jobs"]
  node_style_rules["Style Rules<br/>[styleRules.js]"]
end

node_api_client -->|"sends HTTP requests"| node_express_api
node_express_api -->|"uses middleware"| node_sessions
node_express_api -->|"protects routes"| node_auth
node_express_api -.->|"optional validation"| node_openapi_validation
node_auth -->|"reads session settings"| node_sessions
node_express_api -->|"uses language helpers"| node_languages
node_express_api -->|"delegates operations"| node_documents
node_documents -->|"translates document"| node_languages
node_express_api -->|"delegates operations"| node_glossaries_v2
node_express_api -->|"delegates operations"| node_glossaries_v3
node_glossaries_v3 -->|"parses CSV entries"| node_csv_parser
node_express_api -->|"calls memory operations"| node_translation_memories
node_express_api -->|"calls style operations"| node_style_rules

click node_express_api "https://github.com/deepl/deepl-mock/blob/main/index.js"
click node_sessions "https://github.com/deepl/deepl-mock/blob/main/sessions.js"
click node_auth "https://github.com/deepl/deepl-mock/blob/main/auth.js"
click node_openapi_validation "https://github.com/deepl/deepl-mock/blob/main/response-validator.js"
click node_languages "https://github.com/deepl/deepl-mock/blob/main/languages.js"
click node_documents "https://github.com/deepl/deepl-mock/blob/main/documents.js"
click node_glossaries_v2 "https://github.com/deepl/deepl-mock/blob/main/glossariesV2.js"
click node_glossaries_v3 "https://github.com/deepl/deepl-mock/blob/main/glossariesV3.js"
click node_csv_parser "https://github.com/deepl/deepl-mock/blob/main/glossariesCsvParser.js"
click node_translation_memories "https://github.com/deepl/deepl-mock/blob/main/translationMemories.js"
click node_style_rules "https://github.com/deepl/deepl-mock/blob/main/styleRules.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_client,node_express_api toneBlue
class node_sessions,node_auth,node_openapi_validation toneAmber
class node_languages,node_documents toneMint
class node_glossaries_v2,node_glossaries_v3,node_csv_parser,node_translation_memories,node_style_rules toneRose
```

## Components

### HTTP Entry

- **API Client or Test**: external
- [Express API and Proxy](https://github.com/deepl/deepl-mock/blob/main/index.js): HTTP server · `index.js`

### Request Context

- [Session Middleware](https://github.com/deepl/deepl-mock/blob/main/sessions.js): middleware · `sessions.js`
- [Authentication and Accounts](https://github.com/deepl/deepl-mock/blob/main/auth.js): middleware · `auth.js`
- [OpenAPI Validation](https://github.com/deepl/deepl-mock/blob/main/response-validator.js): middleware · `response-validator.js`

### Translation Services

- [Language and Text Behavior](https://github.com/deepl/deepl-mock/blob/main/languages.js): service · `languages.js`
- [Document Translation](https://github.com/deepl/deepl-mock/blob/main/documents.js): service · `documents.js`

### API Domains

- [v2 Glossaries](https://github.com/deepl/deepl-mock/blob/main/glossariesV2.js): service · `glossariesV2.js`
- [v3 Glossaries](https://github.com/deepl/deepl-mock/blob/main/glossariesV3.js): service · `glossariesV3.js`
- [Glossary CSV Parser](https://github.com/deepl/deepl-mock/blob/main/glossariesCsvParser.js): parser · `glossariesCsvParser.js`
- [Translation Memories and Jobs](https://github.com/deepl/deepl-mock/blob/main/translationMemories.js): service · `translationMemories.js`
- [Style Rules](https://github.com/deepl/deepl-mock/blob/main/styleRules.js): service · `styleRules.js`

## Connections

- API Client or Test → Express API and Proxy: sends HTTP requests
- Express API and Proxy → Session Middleware: uses middleware
- Express API and Proxy → Authentication and Accounts: protects routes
- Express API and Proxy → OpenAPI Validation: optional validation
- Authentication and Accounts → Session Middleware: reads session settings
- Express API and Proxy → Language and Text Behavior: uses language helpers
- Express API and Proxy → Document Translation: delegates operations
- Document Translation → Language and Text Behavior: translates document
- Express API and Proxy → v2 Glossaries: delegates operations
- Express API and Proxy → v3 Glossaries: delegates operations
- v3 Glossaries → Glossary CSV Parser: parses CSV entries
- Express API and Proxy → Translation Memories and Jobs: calls memory operations
- Express API and Proxy → Style Rules: calls style operations