# suitenumerique/docs architecture

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

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

## Overview

La Suite Docs is a collaborative document editor combining structured writing, organization, sharing, search, offline work, conversion, and optional AI. The main user flow is browser access and authentication, then document and hierarchy interaction through the Django API, with the Yjs provider maintaining live shared state and the backend supporting permissions and persistence. Additional branches cover imports/exports, AI, interoperability, and observability. The tree and README establish product scope; edges are limited to explicitly documented or excerpted relationships, so unsampled subsystems are represented without inferred call chains.

Main entry points: [`src/frontend/apps/impress/src/pages/index.tsx`](https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/pages/index.tsx) (Docs interface), [`src/backend/core/api/viewsets.py`](https://github.com/suitenumerique/docs/blob/main/src/backend/core/api/viewsets.py) (Document API), [`src/backend/core/services/yhub_services.py`](https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/yhub_services.py) (YHub client), [`src/frontend/apps/impress/src/api/fetchApi.ts`](https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/api/fetchApi.ts) (Frontend API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web editor"]
  node_web["Docs interface<br/>[index.tsx]"]
  node_auth["Authentication<br/>[useAuth.tsx]"]
  node_api["Frontend API<br/>[fetchApi.ts]"]
  node_offline["Offline sync<br/>[SyncManager.ts]"]
end

subgraph group_backend["Django application"]
  node_models[("Documents and access<br/>[models.py]")]
  node_views["Document API<br/>[viewsets.py]"]
  node_external["Resource API<br/>[viewsets.py]"]
  node_search["Search indexing<br/>[search.py]"]
  node_jwt["JWT services<br/>[jwt_services.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
end

subgraph group_collab["Live collaboration"]
  node_yhubclient["YHub client<br/>[yhub_services.py]"]
  node_yhub["Yjs collaboration<br/>[server.ts]"]
  node_migration["Legacy migration<br/>[migration.ts]"]
end

subgraph group_extensions["Document extensions"]
  node_conversion["Format conversion"]
  node_ai["AI writing<br/>[blocknote.py]"]
  node_provider["Conversion provider<br/>[convertHandler.ts]"]
end

node_user(("Editor"))
node_external_ai(("AI provider"))
node_docspec["DocSpec service"]
node_storage[("S3 document storage")]

node_user -->|"uses"| node_web
node_web -->|"checks session"| node_auth
node_auth -->|"requests user"| node_api
node_web -.->|"calls API"| node_api
node_web -->|"edits offline"| node_offline
node_api -.->|"HTTP requests"| node_views
node_views -.->|"reads and writes"| node_models
node_views -.->|"collaboration actions"| node_yhubclient
node_yhubclient -->|"REST calls"| node_yhub
node_yhub -->|"migrates on startup"| node_migration
node_migration -->|"reads versions"| node_storage
node_yhubclient -->|"signs tokens"| node_jwt
node_conversion -->|"converts DOCX"| node_docspec
node_conversion -->|"converts Yjs"| node_provider
node_ai -.->|"requests models"| node_external_ai
node_external -.->|"serves integrations"| node_user
node_models -->|"indexes changes"| node_search
node_metrics -.->|"observes collaboration"| node_yhub

click node_web "https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/pages/index.tsx"
click node_auth "https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/features/auth/hooks/useAuth.tsx"
click node_api "https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/api/fetchApi.ts"
click node_offline "https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/features/service-worker/SyncManager.ts"
click node_models "https://github.com/suitenumerique/docs/blob/main/src/backend/core/models.py"
click node_views "https://github.com/suitenumerique/docs/blob/main/src/backend/core/api/viewsets.py"
click node_external "https://github.com/suitenumerique/docs/blob/main/src/backend/core/external_api/viewsets.py"
click node_search "https://github.com/suitenumerique/docs/blob/main/src/backend/core/tasks/search.py"
click node_jwt "https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/jwt_services.py"
click node_conversion "https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/converter_services.py"
click node_ai "https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/ai_services/blocknote.py"
click node_yhubclient "https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/yhub_services.py"
click node_yhub "https://github.com/suitenumerique/docs/blob/main/src/yhub-server/src/server.ts"
click node_migration "https://github.com/suitenumerique/docs/blob/main/src/yhub-server/src/migration.ts"
click node_provider "https://github.com/suitenumerique/docs/blob/main/src/frontend/servers/y-provider/src/handlers/convertHandler.ts"
click node_metrics "https://github.com/suitenumerique/docs/blob/main/src/backend/core/metrics.py"

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_web,node_auth,node_api,node_offline toneBlue
class node_models,node_views,node_external,node_search,node_jwt,node_metrics,node_storage toneAmber
class node_yhubclient,node_yhub,node_migration toneMint
class node_conversion,node_ai,node_provider toneRose
class node_user,node_external_ai,node_docspec toneIndigo
```

## Components

### Web editor

- [Docs interface](https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/pages/index.tsx): `src/frontend/apps/impress/src/pages/index.tsx`
- [Authentication](https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/features/auth/hooks/useAuth.tsx): `src/frontend/apps/impress/src/features/auth/hooks/useAuth.tsx`
- [Frontend API](https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/api/fetchApi.ts): `src/frontend/apps/impress/src/api/fetchApi.ts`
- [Offline sync](https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/impress/src/features/service-worker/SyncManager.ts): `src/frontend/apps/impress/src/features/service-worker/SyncManager.ts`

### Django application

- [Documents and access](https://github.com/suitenumerique/docs/blob/main/src/backend/core/models.py): `src/backend/core/models.py`
- [Document API](https://github.com/suitenumerique/docs/blob/main/src/backend/core/api/viewsets.py): `src/backend/core/api/viewsets.py`
- [Resource API](https://github.com/suitenumerique/docs/blob/main/src/backend/core/external_api/viewsets.py): `src/backend/core/external_api/viewsets.py`
- [Search indexing](https://github.com/suitenumerique/docs/blob/main/src/backend/core/tasks/search.py): `src/backend/core/tasks/search.py`
- [JWT services](https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/jwt_services.py): `src/backend/core/services/jwt_services.py`
- [Metrics](https://github.com/suitenumerique/docs/blob/main/src/backend/core/metrics.py): `src/backend/core/metrics.py`

### Live collaboration

- [YHub client](https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/yhub_services.py): `src/backend/core/services/yhub_services.py`
- [Yjs collaboration](https://github.com/suitenumerique/docs/blob/main/src/yhub-server/src/server.ts): `src/yhub-server/src/server.ts`
- [Legacy migration](https://github.com/suitenumerique/docs/blob/main/src/yhub-server/src/migration.ts): `src/yhub-server/src/migration.ts`

### Document extensions

- [Format conversion](https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/converter_services.py): `src/backend/core/services/converter_services.py`
- [AI writing](https://github.com/suitenumerique/docs/blob/main/src/backend/core/services/ai_services/blocknote.py): `src/backend/core/services/ai_services/blocknote.py`
- [Conversion provider](https://github.com/suitenumerique/docs/blob/main/src/frontend/servers/y-provider/src/handlers/convertHandler.ts): `src/frontend/servers/y-provider/src/handlers/convertHandler.ts`

### Other components

- **Editor**
- **AI provider**
- **DocSpec service**
- **S3 document storage**

## Connections

- Editor → Docs interface: uses (evidence: `README.md`)
- Docs interface → Authentication: checks session (evidence: `src/frontend/apps/impress/src/features/auth/hooks/useAuth.tsx`)
- Authentication → Frontend API: requests user
- Docs interface → Frontend API: calls API
- Docs interface → Offline sync: edits offline (evidence: `README.md`)
- Frontend API → Document API: HTTP requests
- Document API → Documents and access: reads and writes
- Document API → YHub client: collaboration actions
- YHub client → Yjs collaboration: REST calls (evidence: `src/backend/core/services/yhub_services.py`)
- Yjs collaboration → Legacy migration: migrates on startup (evidence: `src/yhub-server/src/server.ts`)
- Legacy migration → S3 document storage: reads versions (evidence: `src/yhub-server/src/migration.ts`)
- YHub client → JWT services: signs tokens (evidence: `src/backend/core/services/yhub_services.py`)
- Format conversion → DocSpec service: converts DOCX (evidence: `src/backend/core/services/converter_services.py`)
- Format conversion → Conversion provider: converts Yjs (evidence: `src/backend/core/services/converter_services.py`)
- AI writing → AI provider: requests models
- Resource API → Editor: serves integrations (evidence: `README.md`)
- Documents and access → Search indexing: indexes changes (evidence: `src/backend/core/signals.py`)
- Metrics → Yjs collaboration: observes collaboration
