# pacexy/flow architecture

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

- Interactive diagram: https://gitdiagram.com/pacexy/flow
- Repository: https://github.com/pacexy/flow

## Overview

##### Main Components
- Reader Application (apps/reader)
– This Next.js–based app is the core ePub reader. It contains components for annotations, text selection, custom typography, and other reader features.
– Include subcomponents like UI elements (components folder with buttons, layouts, annotation views, etc.), state and hooks (for remote sync, theming, text selection, etc.), and API endpoints (pages/api for callbacks, refresh, etc.).
- Marketing Website (apps/website)
– This app serves as the public-facing website with product info, screenshots, and static pages (e.g., privacy, terms) built with Next.js and MDX.
- ePub Engine (packages/epubjs)
– A dedicated package that contains core logic to parse, render, and manage ePub documents. It includes modules for annotations, spine, container, pagination, mapping, and various utility functions.
- Shared/Utility Packages
– Internal shared libraries (packages/internal) serve any additional common functionality required by the apps.
– A Tailwind package (packages/tailwind) for global styling, theming, and custom design tokens.
- Infrastructure & Tooling
– Configuration and deployment tools such as Dockerfile, docker-compose.yml, Turborepo (turbo.json), and pnpm setup ensure that the project can be built, run, and deployed consistently.
– Build and linting configuration files (.eslintrc.js, prettier.config.js, tsconfig, etc.) indicate a focus on code quality and a standardized development workflow.

##### Relationships and Interactions
- The UI components and hooks inside the reader interact with backend API endpoints (via Next.js pages/api) to manage annotations, search, share/download links, and integration with cloud storage.
- The website app is related but separate; it primarily serves marketing content and may link to the reader application.
- Shared packages such as internal utilities and Tailwind help maintain consistent styling and common functions across both apps.

##### Architectural Patterns and Design Principles
- API Integration: Highlight the REST or serverless endpoints under apps/reader/pages/api as a separate “backend” block within the reader module.
- Reusability & Modularity: Emphasize that packages like epubjs, internal, and tailwind are designed for reuse across different sub-apps.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Applications
    RA["Reader Application (apps/reader)"]:::nextjs
    RUI["UI Components"]
    RAPI["API Endpoints"]
    RHooks["State & Hooks"]
    RW["Marketing Website (apps/website)"]:::nextjs

    %% Backend / Packages
    Epub["ePub Engine (packages/epubjs)"]:::package
    Shared["Shared Utilities (packages/internal)"]:::package
    Tailwind["Tailwind Package (packages/tailwind)"]:::package

    %% Infrastructure & External Services
    IT["Infrastructure & Tooling"]:::infrastructure
    ReactNX["React & Next.js"]:::external
    Cloud["Cloud Storage/External Services"]:::external

    %% Relationships within Reader Application
    RA --> RUI
    RA --> RAPI
    RA --> RHooks
    RUI -->|"loads"| Epub
    RUI -->|"calls"| RAPI

    %% Dependencies on Shared Packages
    RA -->|"utilizes"| Shared
    RA -->|"styles_with"| Tailwind
    RW -->|"utilizes"| Shared
    RW -->|"styles_with"| Tailwind

    %% External Dependencies
    ReactNX --> RA
    ReactNX --> RW
    Cloud --> RAPI

    %% Infrastructure Support
    IT --> RA
    IT --> RW
    IT --> Epub
    IT --> Shared
    IT --> Tailwind

    %% Click Events
    click RA "https://github.com/pacexy/flow/tree/main/apps/reader"
    click RW "https://github.com/pacexy/flow/tree/main/apps/website"
    click Epub "https://github.com/pacexy/flow/tree/main/packages/epubjs"
    click Shared "https://github.com/pacexy/flow/tree/main/packages/internal"
    click Tailwind "https://github.com/pacexy/flow/tree/main/packages/tailwind"
    click IT "https://github.com/pacexy/flow/tree/main/Dockerfile"

    %% Class Definitions for Coloring
    classDef nextjs fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef package fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef external fill:#D1C4E9,stroke:#333,stroke-width:2px;
```
