# het-t/xdoc-front architecture

> Architecture diagram of the GitHub repository het-t/xdoc-front, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/het-t/xdoc-front
- Repository: https://github.com/het-t/xdoc-front

## Overview

##### Project Type and Purpose
- This is a Single-Page Application (SPA) built with Vue.js and TypeScript.
- The codebase contains no backend server; instead it interacts with external HTTP APIs (e.g., signIn, getSpaces, queryCollection).
- The purpose is to render and manipulate “collections,” “pages,” “blocks,” and user/team data in a Notion-style interface, handling transactions and syncing state with a remote service.

##### File Structure
- Top-Level Directories & Files
– public/: static assets and index.html
– src/: application source
– dist/: built output (CSS, JS bundles, index.html for deployment)
– Configuration: vue.config.js, tsconfig.json, jsconfig.json, ESLint, Prettier and GitHub Actions workflow
- src/ Substructure
– src/main.ts: app bootstrap, Vue instance, router and store registration
– src/ui/: view layer (views/, components/, router/, composables/, helpers/)
– src/entities/: domain model classes (Block, Page, Collection, etc.)
– src/services/
· api/: HTTP client wrappers and endpoint definitions
· transactions/: factories and types to build transaction payloads
– src/stores/: application state (collections, transactionsQueue, teams, recordValues, etc.)
– src/usecases/: pure functions for UI use-cases (listBefore, set, update, etc.)

##### README
- Uses standard Vue CLI setup (webpack, hot-reload, linting).

a. Main Components
- Browser / Client
– Vue.js SPA (App.vue → router → views → components)
– State Management (stores/*)
– Domain Layer (entities/*)
– UI Use-Cases (usecases/* & ui/composables)
- API Layer
– services/api: HTTP calls to external backend
– services/transactions: builds operations and transaction payloads
- External Services
– Remote REST or GraphQL service (authentication, data fetch/update)
b. Relationships & Interactions
- User Events → UI Components → Composables/UseCases → Store Actions
- Store Actions → Transaction Factories → API Calls → Remote Service
- API Response → services/api → stores → UI re-render
- Domain Entities mediate JSON ↔ JavaScript objects
c. Architectural Patterns & Principles
- Layered Architecture (UI → Application Logic → Domain → Infrastructure)
- Separation of Concerns (entities vs. services vs. stores vs. components)
- Transactional Command Pattern (services/transactions factories create operations)
- Modular Folder Structure supporting feature isolation
d. Key Technologies & Frameworks
- Vue.js (components, views, router)
- TypeScript (strong typing for entities, stores, API types)
- Vuex-style stores or Pinia (state management)
- Axios or fetch wrappers in services/api
- Webpack/Vue CLI (build pipeline, hot-reload)

##### Detailed Elements to Capture
– Entry point (main.ts) and routing (vue-router)
– UI composition: views vs. reusable components
– Composables vs. traditional usecases modules
– Entities folder as domain model layer
– services/api vs. services/transactions distinction
– stores covering collections, teams, transactionsQueue, recordValues
– Data flow: how a user action leads to an API call and state update

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Browser
    User["User"]:::user -->|interacts via| Browser["Browser (Vue.js SPA)"]:::browser

    %% Deployment Pipeline
    subgraph "Build & Deploy Pipeline"
        direction TB
        Main["App Bootstrap\n(main.ts)"]:::entry
        Webpack["Webpack Build"]:::process
        Dist["Built Output\n(dist/)"]:::output
        Host["Static Host\n(public/CDN/GitHub Pages)"]:::host
        Main -->|bundles| Webpack -->|outputs| Dist -->|served from| Host
    end

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Router["Routing Module\n(index.ts)"]:::ui
        Breadcrumbs["Router Breadcrumbs\n(breadcrumbs.ts)"]:::ui
        Views["Views\n(views/)"]:::ui
        Components["Reusable Components\n(components/)"]:::ui
        Composables["Composables\n(composables/)"]:::ui
        Router --> Breadcrumbs
        Router --> Views
        Router --> Components
        Router --> Composables
    end

    Browser -->|renders| Router

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        UseCases["UI Use-Cases\n(src/usecases/)"]:::app
        UIHelpers["UI Helpers for Operations\n(operations/)"]:::app
        UseCases --> UIHelpers
    end

    Router -->|dispatches| UseCases

    %% State Management
    Stores["State Store\n(stores/)"]:::store
    Composables -->|reads/writes| Stores
    UseCases -->|commits to| Stores

    %% Domain Layer
    Entities["Domain Entities\n(entities/)"]:::domain
    Stores -->|stores domain objects| Entities
    Composables -->|uses| Entities

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        APISvc["API Services\n(services/api/)"]:::infra
        TxFactories["Transaction Factories\n(services/transactions/factories/)"]:::infra
        TxTypes["Transaction Types\n(services/transactions/types/)"]:::infra
        TxUI["Transaction UI Use-Cases\n(services/transactions/ui-usecases/)"]:::infra
        APISvc -->|calls| TxTypes
        TxFactories -->|builds payloads| APISvc
        TxUI -->|orchestrates| TxFactories
    end

    Stores -->|triggers| TxUI
    TxUI -->|executes| APISvc

    %% External Service
    Remote["Remote Data API\n(External)"]:::external
    APISvc -->|HTTP Requests| Remote
    Remote -->|Responses| APISvc
    APISvc -->|updates| Stores

    %% Global Helpers
    Globals["Global Helpers\n(src/helpers/globals/)"]:::helpers
    Composables --> Globals
    UseCases --> Globals

    %% Static Assets
    Public["Static Assets\n(public/)"]:::public
    Host --> Public

    %% Click Events
    click Main "https://github.com/het-t/xdoc-front/blob/main/src/main.ts"
    click Router "https://github.com/het-t/xdoc-front/blob/main/src/ui/router/index.ts"
    click Breadcrumbs "https://github.com/het-t/xdoc-front/blob/main/src/ui/router/breadcrumbs.ts"
    click Views "https://github.com/het-t/xdoc-front/tree/main/src/ui/views/"
    click Components "https://github.com/het-t/xdoc-front/tree/main/src/ui/components/"
    click Composables "https://github.com/het-t/xdoc-front/tree/main/src/ui/composables/"
    click UseCases "https://github.com/het-t/xdoc-front/tree/main/src/usecases/"
    click UIHelpers "https://github.com/het-t/xdoc-front/tree/main/src/ui/helpers/operations/"
    click Entities "https://github.com/het-t/xdoc-front/tree/main/src/entities/"
    click APISvc "https://github.com/het-t/xdoc-front/tree/main/src/services/api/"
    click TxFactories "https://github.com/het-t/xdoc-front/tree/main/src/services/transactions/factories/"
    click TxTypes "https://github.com/het-t/xdoc-front/tree/main/src/services/transactions/types/"
    click TxUI "https://github.com/het-t/xdoc-front/tree/main/src/services/transactions/ui-usecases/"
    click Stores "https://github.com/het-t/xdoc-front/tree/main/src/stores/"
    click Globals "https://github.com/het-t/xdoc-front/tree/main/src/helpers/globals/"
    click Public "https://github.com/het-t/xdoc-front/tree/main/public/"
    click Dist "https://github.com/het-t/xdoc-front/tree/main/dist/"

    %% Styles
    classDef user fill:#a3e4ff,stroke:#333,stroke-width:1px;
    classDef browser fill:#d0e6f7,stroke:#333,stroke-width:1px;
    classDef entry fill:#cfe2f3,stroke:#333,stroke-width:1px;
    classDef process fill:#ffe699,stroke:#333,stroke-width:1px;
    classDef output fill:#d9ead3,stroke:#333,stroke-width:1px;
    classDef host fill:#f4cccc,stroke:#333,stroke-width:1px;
    classDef ui fill:#9fc5e8,stroke:#333,stroke-width:1px;
    classDef app fill:#b4a7d6,stroke:#333,stroke-width:1px;
    classDef store fill:#b6d7a8,stroke:#333,stroke-width:1px;
    classDef domain fill:#fff2cc,stroke:#333,stroke-width:1px;
    classDef infra fill:#f9cb9c,stroke:#333,stroke-width:1px;
    classDef external fill:#d9d2e9,stroke:#333,stroke-width:1px;
    classDef helpers fill:#d0b7d5,stroke:#333,stroke-width:1px;
    classDef public fill:#e2efda,stroke:#333,stroke-width:1px;
```
