# rayssaareis/bureaucracy-translator architecture

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

- Interactive diagram: https://gitdiagram.com/rayssaareis/bureaucracy-translator
- Repository: https://github.com/rayssaareis/bureaucracy-translator

## Overview

Bureaucracy Translator accepts pasted text or a document image, validates the request, and returns a plain-language explanation with next steps in the selected language. The frontend validates and submits input; the backend routes text directly to Gemini or extracts image text through OCR.space before using the same Gemini flow. The map also includes response/error handling and the documented frontend capabilities. Source excerpts show the main calls; some frontend features and static serving are documented in the README rather than inspected in source.

Main entry points: [`src/main/resources/static/js/app.js`](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/app.js) (Input and results UI), [`src/main/java/com/bureaucracytranslator/service/TranslateService.java`](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/service/TranslateService.java) (Translation workflow), [`src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java`](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java) (Global error mapping), [`src/main/java/com/bureaucracytranslator/client/GeminiClient.java`](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/client/GeminiClient.java) (Gemini client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Static frontend"]
  node_ui["Input and results UI<br/>[app.js]"]
  node_validation["Input validation<br/>[validation.js]"]
  node_webapi["API client<br/>[api.js]"]
  node_webconfig["UI configuration<br/>[config.js]"]
end

subgraph group_api["Request handling"]
  node_controller["Translate endpoint"]
end

subgraph group_processing["Document processing"]
  node_service["Translation workflow"]
  node_ocr["OCR.space client"]
  node_ocrconfig["OCR settings"]
  node_gemini["Gemini client<br/>[GeminiClient.java]"]
  node_gconfig["Gemini settings"]
  node_translation["Structured translation"]
end

subgraph group_errors["Response handling"]
  node_errors["Global error mapping"]
  node_errorresponse["Error response<br/>[ErrorResponse.java]"]
  node_invalid["Request validation error"]
  node_ocrerror["OCR service error"]
  node_geminierror["Gemini service error"]
end

node_user(("User"))
node_ocrservice{{"OCR.space"}}
node_geminiservice{{"Gemini API"}}

node_user -->|"enters or uploads"| node_ui
node_ui -->|"validates input"| node_validation
node_ui -->|"submits translation"| node_webapi
node_ui -->|"reads settings"| node_webconfig
node_webapi -->|"reads API URL"| node_webconfig
node_webapi -->|"POSTs request"| node_controller
node_controller -->|"routes text or image"| node_service
node_service -->|"extracts image text"| node_ocr
node_ocr -->|"sends image"| node_ocrservice
node_ocr -->|"reads credentials"| node_ocrconfig
node_service -->|"requests explanation"| node_gemini
node_gemini -->|"generates explanation"| node_geminiservice
node_gemini -->|"reads model and key"| node_gconfig
node_gemini -->|"parses structured output"| node_translation
node_ui -->|"displays result"| node_translation
node_controller -->|"rejects invalid requests"| node_invalid
node_errors -->|"builds error body"| node_errorresponse
node_errors -->|"maps request errors"| node_invalid
node_errors -->|"maps OCR errors"| node_ocrerror
node_errors -->|"maps Gemini errors"| node_geminierror
node_service -->|"raises on invalid output"| node_geminierror
node_service -->|"rejects unusable OCR text"| node_invalid

click node_ui "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/app.js"
click node_validation "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/validation.js"
click node_webapi "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/api.js"
click node_webconfig "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/config.js"
click node_controller "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/controller/TranslateController.java"
click node_service "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/service/TranslateService.java"
click node_ocr "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/client/OcrSpaceClient.java"
click node_ocrconfig "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/config/OcrSpaceProperties.java"
click node_gemini "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/client/GeminiClient.java"
click node_gconfig "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/config/GeminiProperties.java"
click node_translation "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/dto/TranslateResponse.java"
click node_errors "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java"
click node_errorresponse "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/dto/ErrorResponse.java"
click node_invalid "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/InvalidRequestException.java"
click node_ocrerror "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/OcrServiceException.java"
click node_geminierror "https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/GeminiServiceException.java"

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_ui,node_validation,node_webapi,node_webconfig,node_user toneBlue
class node_controller toneAmber
class node_service,node_ocr,node_ocrconfig,node_gemini,node_gconfig,node_translation,node_geminiservice toneMint
class node_errors,node_errorresponse,node_invalid,node_ocrerror,node_geminierror toneRose
class node_ocrservice toneIndigo
```

## Components

### Static frontend

- [Input and results UI](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/app.js): `src/main/resources/static/js/app.js`
- [Input validation](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/validation.js): `src/main/resources/static/js/validation.js`
- [API client](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/api.js): `src/main/resources/static/js/api.js`
- [UI configuration](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/resources/static/js/config.js): `src/main/resources/static/js/config.js`

### Request handling

- [Translate endpoint](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/controller/TranslateController.java): `src/main/java/com/bureaucracytranslator/controller/TranslateController.java`

### Document processing

- [Translation workflow](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/service/TranslateService.java): `src/main/java/com/bureaucracytranslator/service/TranslateService.java`
- [OCR.space client](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/client/OcrSpaceClient.java): `src/main/java/com/bureaucracytranslator/client/OcrSpaceClient.java`
- [OCR settings](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/config/OcrSpaceProperties.java): `src/main/java/com/bureaucracytranslator/config/OcrSpaceProperties.java`
- [Gemini client](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/client/GeminiClient.java): `src/main/java/com/bureaucracytranslator/client/GeminiClient.java`
- [Gemini settings](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/config/GeminiProperties.java): `src/main/java/com/bureaucracytranslator/config/GeminiProperties.java`
- [Structured translation](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/dto/TranslateResponse.java): `src/main/java/com/bureaucracytranslator/dto/TranslateResponse.java`

### Response handling

- [Global error mapping](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java): `src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java`
- [Error response](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/dto/ErrorResponse.java): `src/main/java/com/bureaucracytranslator/dto/ErrorResponse.java`
- [Request validation error](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/InvalidRequestException.java): `src/main/java/com/bureaucracytranslator/exception/InvalidRequestException.java`
- [OCR service error](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/OcrServiceException.java): `src/main/java/com/bureaucracytranslator/exception/OcrServiceException.java`
- [Gemini service error](https://github.com/rayssaareis/bureaucracy-translator/blob/main/src/main/java/com/bureaucracytranslator/exception/GeminiServiceException.java): `src/main/java/com/bureaucracytranslator/exception/GeminiServiceException.java`

### Other components

- **User**
- **OCR.space**
- **Gemini API**

## Connections

- User → Input and results UI: enters or uploads (evidence: `README.md`)
- Input and results UI → Input validation: validates input (evidence: `src/main/resources/static/js/app.js`)
- Input and results UI → API client: submits translation (evidence: `src/main/resources/static/js/app.js`)
- Input and results UI → UI configuration: reads settings (evidence: `src/main/resources/static/js/app.js`)
- API client → UI configuration: reads API URL (evidence: `src/main/resources/static/js/api.js`)
- API client → Translate endpoint: POSTs request (evidence: `README.md`)
- Translate endpoint → Translation workflow: routes text or image (evidence: `src/main/java/com/bureaucracytranslator/controller/TranslateController.java`)
- Translation workflow → OCR.space client: extracts image text (evidence: `src/main/java/com/bureaucracytranslator/service/TranslateService.java`)
- OCR.space client → OCR.space: sends image (evidence: `README.md`)
- OCR.space client → OCR settings: reads credentials (evidence: `src/main/java/com/bureaucracytranslator/client/OcrSpaceClient.java`)
- Translation workflow → Gemini client: requests explanation (evidence: `src/main/java/com/bureaucracytranslator/service/TranslateService.java`)
- Gemini client → Gemini API: generates explanation (evidence: `README.md`)
- Gemini client → Gemini settings: reads model and key (evidence: `src/main/java/com/bureaucracytranslator/client/GeminiClient.java`)
- Gemini client → Structured translation: parses structured output (evidence: `src/main/java/com/bureaucracytranslator/client/GeminiClient.java`)
- Input and results UI → Structured translation: displays result (evidence: `README.md`)
- Translate endpoint → Request validation error: rejects invalid requests (evidence: `src/main/java/com/bureaucracytranslator/controller/TranslateController.java`)
- Global error mapping → Error response: builds error body (evidence: `src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java`)
- Global error mapping → Request validation error: maps request errors (evidence: `src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java`)
- Global error mapping → OCR service error: maps OCR errors (evidence: `src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java`)
- Global error mapping → Gemini service error: maps Gemini errors (evidence: `src/main/java/com/bureaucracytranslator/exception/GlobalExceptionHandler.java`)
- Translation workflow → Gemini service error: raises on invalid output (evidence: `src/main/java/com/bureaucracytranslator/service/TranslateService.java`)
- Translation workflow → Request validation error: rejects unusable OCR text (evidence: `src/main/java/com/bureaucracytranslator/service/TranslateService.java`)
