# cozy/cozy-drive architecture

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

- Interactive diagram: https://gitdiagram.com/cozy/cozy-drive
- Repository: https://github.com/cozy/cozy-drive

## Overview

##### Project type and purpose
- This is a single-page application (SPA) written in React, built to serve as the frontend “Drive” app of the Cozy platform. Its goal is to let users browse, upload, share, and edit files and folders, integrating deeply with the Cozy backend (“cozy-stack”) and external services like OnlyOffice and Nextcloud.

##### High-level architecture components
a. User’s Browser (Client)
b. Frontend Application
- React component tree under src/components & src/modules
- State management (Redux-style) in src/store (configureStore, rootReducer)
- Custom Hooks in src/hooks
- Context providers in src/lib (e.g., DriveProvider, ModalContext)
- Feature modules (e.g., upload, viewer, search, nextcloud integrations)
- I18n layer via Transifex and src/locales
c. API Client
- cozy-client-js used by the app to call cozy-stack HTTP/JSON endpoints
- Web Push (pushClient) for real-time updates
d. External Services
- OnlyOffice server for document editing (embedded via src/modules/views/OnlyOffice)
- Nextcloud APIs for mounting external drives
e. Backend (cozy-stack)
- Hosts the REST API endpoints, authentication, file storage, sharing logic
- Mailing service (MailHog in dev) for sharing flows
f. Build & Deployment
- rsbuild/webpack config under rsbuild.config.mjs & babel.config.js
- Targets: browser, public, intents, services
- CI/CD pipelines in .github/workflows (ci-cd.yml, codeql-analysis.yml)

##### Relationships & dataflows
- Browser ⇄ React SPA: user actions trigger component updates
- SPA → cozy-client-js → cozy-stack API: fetch folder entries, upload/download files, share/unshare, search
- SPA → Web Push endpoint → pushClient listener → update UI in real time
- SPA ↔ OnlyOffice via iframe/embed URL + postMessage callbacks for live document editing
- SPA ↔ Nextcloud via dedicated Nextcloud API hooks to display and operate on Nextcloud drives
- CI/CD: Source code → GitHub Actions → build artifacts → cozy-stack serve (dev) or static hosting (prod)

##### Architectural patterns & design principles
- Modular, feature-based folder structure under src/modules for separation of concerns
- Presentational vs. container components; Hooks for logic reuse
- Context API + custom providers for cross-cutting concerns (modal management, theming)
- Redux-style store, actions, and selectors for global state
- Hot Module Replacement and code splitting by entry point (browser, public)
- Testing strategy using Jest with setup in jest.config.js and jestHelpers

##### Technologies & frameworks
- React + JSX/TSX, Babel, Webpack/rsbuild
- Redux (store) + redux-thunk or sagas (async actions in src/modules)
- Jest + chai + sinon for unit/integration tests
- Stylus for styling (src/styles & .styl files in modules)
- Transifex CLI for i18n
- Yarn as package manager, GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        ReactUI["React Component Tree"]:::frontend
    end

    %% State & Logic Layer
    subgraph "State & Logic Layer"
        ReduxStore["Redux Store"]:::state
        Hooks["Custom Hooks"]:::state
        DriveProvider["DriveProvider"]:::state
        ModalContext["ModalContext"]:::state
        FabProvider["FabProvider"]:::state
        ThumbnailContext["ThumbnailSizeContext"]:::state
        I18n["I18n Layer"]:::state
    end

    %% Feature Modules
    subgraph "Feature Modules"
        Upload["Upload Module"]:::frontend
        Viewer["Viewer Module"]:::frontend
        Search["Search Module"]:::frontend
        NextcloudMod["Nextcloud Integration Module"]:::frontend
        OnlyOfficeMod["OnlyOffice Integration Module"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        APIClient["cozy-client-js API Client"]:::api
        WebPushClient["pushClient"]:::api
        PushBanner["PushBanner"]:::api
    end

    %% External Services
    subgraph "External Services"
        OnlyOfficeExt["OnlyOffice Server"]:::external
        NextcloudExt["Nextcloud APIs"]:::external
    end

    %% Backend Layer
    subgraph "Backend Layer"
        Backend["cozy-stack REST API"]:::backend
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        RSBuild["rsbuild.config.mjs"]:::pipeline
        Babel["babel.config.js"]:::pipeline
        TargetBrowser["Browser Target"]:::pipeline
        TargetPublic["Public Target"]:::pipeline
        TargetIntents["Intents Target"]:::pipeline
        TargetServices["Services Target"]:::pipeline
        CI1[".github/workflows/ci-cd.yml"]:::pipeline
        CI2[".github/workflows/codeql-analysis.yml"]:::pipeline
    end

    %% Connections
    ReactUI -->|uses| ReduxStore
    ReactUI -->|uses| Hooks
    ReactUI -->|uses| DriveProvider
    ReactUI -->|uses| ModalContext
    ReactUI -->|uses| FabProvider
    ReactUI -->|uses| ThumbnailContext
    ReactUI -->|renders| Upload
    ReactUI -->|renders| Viewer
    ReactUI -->|renders| Search
    ReactUI -->|renders| NextcloudMod
    ReactUI -->|renders| OnlyOfficeMod

    ReduxStore -->|dispatches to| APIClient
    Hooks -->|calls| APIClient
    DriveProvider -->|provides to| ReactUI
    ModalContext -->|provides to| ReactUI
    FabProvider -->|provides to| ReactUI
    ThumbnailContext -->|provides to| ReactUI
    I18n -->|localizes| ReactUI

    Upload -->|API calls| APIClient
    Viewer -->|API calls| APIClient
    Search -->|API calls| APIClient
    NextcloudMod -->|API calls| APIClient
    OnlyOfficeMod -->|API calls| APIClient

    ReactUI -->|listens| WebPushClient
    ReactUI -->|displays| PushBanner
    WebPushClient -->|subscribes| Backend
    APIClient -->|crud endpoints| Backend

    OnlyOfficeMod -->|embed/postMessage| OnlyOfficeExt
    ReactUI -->|mount/mountApi| NextcloudExt

    CI1 -->|triggers| RSBuild
    CI2 -->|triggers| RSBuild
    RSBuild -->|uses| Babel
    RSBuild -->|builds| TargetBrowser
    RSBuild -->|builds| TargetPublic
    RSBuild -->|builds| TargetIntents
    RSBuild -->|builds| TargetServices
    TargetBrowser -->|artifacts| ReactUI
    TargetPublic -->|artifacts| ReactUI
    TargetIntents -->|artifacts| ReactUI
    TargetServices -->|artifacts| ReactUI

    %% Click Events
    click ReactUI "https://github.com/cozy/cozy-drive/tree/master/src/components"
    click ReactUI "https://github.com/cozy/cozy-drive/tree/master/src/modules"
    click ReduxStore "https://github.com/cozy/cozy-drive/blob/master/src/store/configureStore.js"
    click ReduxStore "https://github.com/cozy/cozy-drive/blob/master/src/store/rootReducer.js"
    click Hooks "https://github.com/cozy/cozy-drive/tree/master/src/hooks"
    click DriveProvider "https://github.com/cozy/cozy-drive/blob/master/src/lib/DriveProvider.jsx"
    click ModalContext "https://github.com/cozy/cozy-drive/blob/master/src/lib/ModalContext.tsx"
    click FabProvider "https://github.com/cozy/cozy-drive/blob/master/src/lib/FabProvider.jsx"
    click ThumbnailContext "https://github.com/cozy/cozy-drive/blob/master/src/lib/ThumbnailSizeContext.tsx"
    click Upload "https://github.com/cozy/cozy-drive/tree/master/src/modules/upload"
    click Viewer "https://github.com/cozy/cozy-drive/tree/master/src/modules/viewer"
    click Search "https://github.com/cozy/cozy-drive/tree/master/src/modules/search"
    click NextcloudMod "https://github.com/cozy/cozy-drive/tree/master/src/modules/nextcloud"
    click OnlyOfficeMod "https://github.com/cozy/cozy-drive/tree/master/src/modules/views/OnlyOffice"
    click OnlyOfficeMod "https://github.com/cozy/cozy-drive/tree/master/src/assets/onlyOffice"
    click I18n "https://github.com/cozy/cozy-drive/tree/master/src/locales"
    click I18n "https://github.com/cozy/cozy-drive/blob/master/.transifexrc.tpl"
    click I18n "https://github.com/cozy/cozy-drive/tree/master/tx/config"
    click APIClient "https://github.com/cozy/cozy-drive/blob/master/src/lib/registerClientPlugins.js"
    click WebPushClient "https://github.com/cozy/cozy-drive/tree/master/src/components/pushClient"
    click PushBanner "https://github.com/cozy/cozy-drive/tree/master/src/components/PushBanner"
    click RSBuild "https://github.com/cozy/cozy-drive/blob/master/rsbuild.config.mjs"
    click Babel "https://github.com/cozy/cozy-drive/blob/master/babel.config.js"
    click TargetBrowser "https://github.com/cozy/cozy-drive/tree/master/src/targets/browser"
    click TargetPublic "https://github.com/cozy/cozy-drive/tree/master/src/targets/public"
    click TargetIntents "https://github.com/cozy/cozy-drive/tree/master/src/targets/intents"
    click TargetServices "https://github.com/cozy/cozy-drive/tree/master/src/targets/services"
    click CI1 "https://github.com/cozy/cozy-drive/blob/master/.github/workflows/ci-cd.yml"
    click CI2 "https://github.com/cozy/cozy-drive/blob/master/.github/workflows/codeql-analysis.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef state fill:#E8F4F8,stroke:#0366d6,stroke-width:1px
    classDef api fill:#DFF5E1,stroke:#28a745,stroke-width:1px
    classDef external fill:#E6FFFA,stroke:#1BB394,stroke-width:1px
    classDef backend fill:#FFE8D6,stroke:#FFA500,stroke-width:1px
    classDef pipeline stroke-dasharray: 5 5,fill:#F0F0F0,stroke:#888,stroke-width:1px
```
