# tetsuuya/docs-service architecture

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

- Interactive diagram: https://gitdiagram.com/tetsuuya/docs-service
- Repository: https://github.com/tetsuuya/docs-service

## Overview

Docs-Service accepts document-generation requests through an Express API and returns generated files. The main workflow branches by format and mode: DOCX can be generated from scratch, filled against an uploaded or master template, or informed by a reference document; PPTX generation is a separate capability, with image-generation support; XLSX generation is exposed, while PDF conversion is present but explicitly unfinished. The sampled code supports the DOCX orchestration and Gemini calls; several PPTX/XLSX internals were not sampled, so their wiring is shown only where evidenced.

Main entry points: [`src/controllers/documentController.js`](https://github.com/tetsuuya/docs-service/blob/main/src/controllers/documentController.js) (Generation controller), [`src/services/docx/fill/fillModeService.js`](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/fillModeService.js) (Template fill mode), [`src/routes/documentRoutes.js`](https://github.com/tetsuuya/docs-service/blob/main/src/routes/documentRoutes.js) (Document routes), [`src/services/docx/scratch/scratchModeService.js`](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/scratch/scratchModeService.js) (Scratch content)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Web API"]
  node_frontend["Web frontend<br/>[index.html]"]
  node_app["Express app<br/>[app.js]"]
  node_routes["Document routes<br/>[documentRoutes.js]"]
  node_controller["Generation controller"]
end

subgraph group_docx["DOCX Generation"]
  node_scratchdoc["Scratch content"]
  node_scratchbuilder["Scratch DOCX builder"]
  node_template["Template analysis<br/>[templateService.js]"]
  node_fillmode["Template fill mode<br/>[fillModeService.js]"]
  node_htmlplan["HTML DOCX planning"]
  node_htmlbuilder["HTML DOCX builder<br/>[htmlDocxBuilder.js]"]
  node_fillbuilder["Fill DOCX builder<br/>[fillDocxBuilder.js]"]
end

subgraph group_pptx["Presentation Generation"]
  node_pptservice["PPTX service<br/>[pptxService.js]"]
  node_pptcontent["PPTX content generation"]
  node_pptbuilder["Scratch PPTX builder"]
  node_pptfill["PPTX fill builder<br/>[fillPptxBuilder.js]"]
  node_pptplan["PPTX fill planning"]
  node_ppthtmlplan["HTML PPTX planning"]
  node_ppthtmlbuilder["HTML PPTX builder<br/>[htmlPptxBuilder.js]"]
  node_pptreference["Reference PPTX builder"]
  node_ppttemplate["PPTX template parsing<br/>[templateParser.js]"]
  node_images["Image service<br/>[imageService.js]"]
end

subgraph group_formats["Other Formats"]
  node_xlsx["XLSX generator<br/>[xlsxService.js]"]
  node_pdf["PDF conversion<br/>[pdfService.js]"]
end

subgraph group_state["History"]
  node_history[("Document history<br/>[historyStorage.js]")]
end

node_user(("Requesting user"))
node_gemini{{"Gemini API"}}
node_imageproviders{{"Image providers"}}

node_user -->|"submits prompt"| node_frontend
node_user -->|"posts request"| node_routes
node_frontend -->|"uses service"| node_app
node_app -->|"mounts API"| node_routes
node_routes -->|"dispatches"| node_controller
node_controller -->|"generates content"| node_scratchdoc
node_controller -->|"builds DOCX"| node_scratchbuilder
node_controller -->|"fills template"| node_fillmode
node_controller -->|"analyzes upload"| node_template
node_controller -->|"builds filled DOCX"| node_fillbuilder
node_fillmode -->|"creates plan"| node_htmlplan
node_htmlplan -->|"requests content"| node_gemini
node_fillmode -->|"builds HTML DOCX"| node_htmlbuilder
node_fillmode -->|"requests AI content"| node_scratchdoc
node_scratchdoc -->|"requests content"| node_gemini
node_controller -->|"saves document"| node_history
node_controller -->|"requests PPTX"| node_pptservice
node_controller -->|"requests XLSX"| node_xlsx
node_controller -->|"requests PDF"| node_pdf
node_pptcontent -->|"requests slides"| node_gemini
node_images -.->|"fetches images"| node_imageproviders

click node_frontend "https://github.com/tetsuuya/docs-service/blob/main/public/index.html"
click node_app "https://github.com/tetsuuya/docs-service/blob/main/src/app.js"
click node_routes "https://github.com/tetsuuya/docs-service/blob/main/src/routes/documentRoutes.js"
click node_controller "https://github.com/tetsuuya/docs-service/blob/main/src/controllers/documentController.js"
click node_scratchdoc "https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/scratch/scratchModeService.js"
click node_scratchbuilder "https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/scratch/scratchDocxBuilder.js"
click node_template "https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/shared/templateService.js"
click node_fillmode "https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/fillModeService.js"
click node_htmlplan "https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/htmlDocxPlanGenerator.js"
click node_htmlbuilder "https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/htmlDocxBuilder.js"
click node_fillbuilder "https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/fillDocxBuilder.js"
click node_pptservice "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/pptxService.js"
click node_pptcontent "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/scratch/scratchPptxService.js"
click node_pptbuilder "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/scratch/scratchPptxBuilder.js"
click node_pptfill "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/fill/fillPptxBuilder.js"
click node_pptplan "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/fill/pptxPlanGenerator.js"
click node_ppthtmlplan "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/fill/htmlPptxPlanGenerator.js"
click node_ppthtmlbuilder "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/fill/htmlPptxBuilder.js"
click node_pptreference "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/reference/referencePptxBuilder.js"
click node_ppttemplate "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/template/templateParser.js"
click node_images "https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/imageService.js"
click node_xlsx "https://github.com/tetsuuya/docs-service/blob/main/src/services/xlsx/xlsxService.js"
click node_pdf "https://github.com/tetsuuya/docs-service/blob/main/src/services/pdf/pdfService.js"
click node_history "https://github.com/tetsuuya/docs-service/blob/main/src/utils/historyStorage.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_frontend,node_app,node_routes,node_controller,node_user toneBlue
class node_scratchdoc,node_scratchbuilder,node_template,node_fillmode,node_htmlplan,node_htmlbuilder,node_fillbuilder toneAmber
class node_pptservice,node_pptcontent,node_pptbuilder,node_pptfill,node_pptplan,node_ppthtmlplan,node_ppthtmlbuilder,node_pptreference,node_ppttemplate,node_images,node_gemini toneMint
class node_xlsx,node_pdf toneRose
class node_history,node_imageproviders toneIndigo
```

## Components

### Web API

- [Web frontend](https://github.com/tetsuuya/docs-service/blob/main/public/index.html): `public/index.html`
- [Express app](https://github.com/tetsuuya/docs-service/blob/main/src/app.js): `src/app.js`
- [Document routes](https://github.com/tetsuuya/docs-service/blob/main/src/routes/documentRoutes.js): `src/routes/documentRoutes.js`
- [Generation controller](https://github.com/tetsuuya/docs-service/blob/main/src/controllers/documentController.js): `src/controllers/documentController.js`

### DOCX Generation

- [Scratch content](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/scratch/scratchModeService.js): `src/services/docx/scratch/scratchModeService.js`
- [Scratch DOCX builder](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/scratch/scratchDocxBuilder.js): `src/services/docx/scratch/scratchDocxBuilder.js`
- [Template analysis](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/shared/templateService.js): `src/services/docx/shared/templateService.js`
- [Template fill mode](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/fillModeService.js): `src/services/docx/fill/fillModeService.js`
- [HTML DOCX planning](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/htmlDocxPlanGenerator.js): `src/services/docx/fill/htmlDocxPlanGenerator.js`
- [HTML DOCX builder](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/htmlDocxBuilder.js): `src/services/docx/fill/htmlDocxBuilder.js`
- [Fill DOCX builder](https://github.com/tetsuuya/docs-service/blob/main/src/services/docx/fill/fillDocxBuilder.js): `src/services/docx/fill/fillDocxBuilder.js`

### Presentation Generation

- [PPTX service](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/pptxService.js): `src/services/pptx/pptxService.js`
- [PPTX content generation](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/scratch/scratchPptxService.js): `src/services/pptx/scratch/scratchPptxService.js`
- [Scratch PPTX builder](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/scratch/scratchPptxBuilder.js): `src/services/pptx/scratch/scratchPptxBuilder.js`
- [PPTX fill builder](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/fill/fillPptxBuilder.js): `src/services/pptx/fill/fillPptxBuilder.js`
- [PPTX fill planning](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/fill/pptxPlanGenerator.js): `src/services/pptx/fill/pptxPlanGenerator.js`
- [HTML PPTX planning](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/fill/htmlPptxPlanGenerator.js): `src/services/pptx/fill/htmlPptxPlanGenerator.js`
- [HTML PPTX builder](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/fill/htmlPptxBuilder.js): `src/services/pptx/fill/htmlPptxBuilder.js`
- [Reference PPTX builder](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/reference/referencePptxBuilder.js): `src/services/pptx/reference/referencePptxBuilder.js`
- [PPTX template parsing](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/template/templateParser.js): `src/services/pptx/template/templateParser.js`
- [Image service](https://github.com/tetsuuya/docs-service/blob/main/src/services/pptx/imageService.js): `src/services/pptx/imageService.js`

### Other Formats

- [XLSX generator](https://github.com/tetsuuya/docs-service/blob/main/src/services/xlsx/xlsxService.js): `src/services/xlsx/xlsxService.js`
- [PDF conversion](https://github.com/tetsuuya/docs-service/blob/main/src/services/pdf/pdfService.js): `src/services/pdf/pdfService.js`

### History

- [Document history](https://github.com/tetsuuya/docs-service/blob/main/src/utils/historyStorage.js): `src/utils/historyStorage.js`

### Other components

- **Requesting user**
- **Gemini API**
- **Image providers**

## Connections

- Requesting user → Web frontend: submits prompt
- Requesting user → Document routes: posts request
- Web frontend → Express app: uses service
- Express app → Document routes: mounts API
- Document routes → Generation controller: dispatches
- Generation controller → Scratch content: generates content
- Generation controller → Scratch DOCX builder: builds DOCX
- Generation controller → Template fill mode: fills template
- Generation controller → Template analysis: analyzes upload
- Generation controller → Fill DOCX builder: builds filled DOCX
- Template fill mode → HTML DOCX planning: creates plan
- HTML DOCX planning → Gemini API: requests content
- Template fill mode → HTML DOCX builder: builds HTML DOCX
- Template fill mode → Scratch content: requests AI content
- Scratch content → Gemini API: requests content
- Generation controller → Document history: saves document
- Generation controller → PPTX service: requests PPTX
- Generation controller → XLSX generator: requests XLSX
- Generation controller → PDF conversion: requests PDF
- PPTX content generation → Gemini API: requests slides
- Image service → Image providers: fetches images