# teamcoderz/wordyme architecture

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

- Interactive diagram: https://gitdiagram.com/teamcoderz/wordyme
- Repository: https://github.com/teamcoderz/wordyme

## Overview

1. **Repository shape**
   - This is a Turborepo monorepo with two deployable apps: `apps/web` (React/Vite frontend) and `apps/backend` (Express API).
   - Shared behavior is pushed into packages under `packages/` so the UI, editor, types, SDK, and utility logic can be reused cleanly across apps.

2. **Primary runtime boundary**
   - The backend is the system of record. It owns authentication, persistence, document lifecycle, search, revisions, favorites, editor settings, and file/storage access.
   - The web app is a client shell that renders routes, manages local UI state, and talks to the backend through an SDK and query layer.

3. **Frontend composition**
   - `apps/web` is a React 19 app built with Vite and TanStack Router for file-based route boundaries.
   - TanStack Query handles server state; Zustand stores handle client state such as tabs, UI, auth/user state, and editor-related ephemeral state.
   - Most user-facing screens are organized by domain: documents, spaces, settings, auth, and the split-pane/tabbed document workspace.

4. **Backend composition**
   - `apps/backend/src/routes` contains the HTTP surface area, split by feature: auth state, documents, revisions, favorites, editor settings, storage, and health.
   - `services/` contains business logic, while `models/` map to database tables and `schemas/` define Zod validation for request/response contracts.
   - `lib/` contains foundational concerns such as auth, DB access, socket setup, storage, and docs helpers.

5. **Persistence and data model**
   - The backend uses Drizzle ORM with libSQL/SQLite as the primary database, with migrations stored under `apps/backend/drizzle`.
   - Key data domains include documents, revisions, favorites, document views, search index entries, editor settings, user images, and auth-related state.
   - There is a filesystem storage area under `apps/backend/storage`, indicating binary assets and/or local database persistence live outside the HTTP layer.

6. **Document workflow**
   - Documents are central: create/read/update/manage flows run from web UI routes and components into backend document routes, then through document services/models.
   - Revisions are first-class, with separate revision routes/services/models, so edits can be stored and browsed as history rather than only current state.
   - Search is indexed separately via `document-search-index`, implying document text is extracted and maintained in a query-friendly form.

7. **Rich editor subsystem**
   - `packages/editor` is a large standalone Lexical-based editor/viewer package used by the web app for editing and rendering documents.
   - It includes custom nodes, plugins, dialogs, toolbar controls, markdown handling, math, diagrams, attachments, page layout, and table support.
   - This package is a major architectural boundary: editor behavior is mostly isolated from app shell logic and can be reused by both editor and viewer modes.

8. **Attachments, images, and media**
   - Attachments and user images are handled as dedicated backend domains and also surfaced in the editor package and web document sidebar/UI.
   - The backend’s storage route plus `services/attachments.ts` and `services/images.ts` suggest media is uploaded/served separately from normal JSON APIs.
   - The editor package includes attachment-aware nodes and image utilities, so document content can embed external media references rather than inline blobs.

9. **Authentication and access control**
   - Authentication is handled on the backend via Better Auth, with a dedicated auth-state route and auth middleware.
   - Access control is enforced through backend middleware and access services, meaning route handlers are not the only authorization boundary.
   - The web app has separate unauthed and authed route trees, so navigation state reflects auth state at the router level.

10. **Real-time behavior**
   - Socket.io is wired through backend `lib/socket.ts` and the web `RealtimeProvider`, so some document/editor state is synchronized live.
   - The SDK also has a realtime client package, indicating WebSocket communication is abstracted away from feature code.
   - This is likely used for collaborative or near-real-time updates around documents and editor presence/state.

11. **Client/server contract boundary**
   - `packages/sdk` encapsulates backend API access for the web app, keeping fetch/axios details out of feature components.
   - `packages/types` centralizes shared domain types for documents, revisions, spaces, users, navigation, tabs, and UI.
   - This split is important for architecture diagrams: UI features depend on SDK + types, not directly on backend internals.

12. **Shared UI and utility packages**
   - `packages/ui` is the general component library for buttons, dialogs, tables, sidebars, forms, theme, and reusable layout primitives.
   - `packages/shared` and `packages/lib` provide cross-cutting pure utilities such as UUIDs, environment handling, keyboard helpers, checksums, tree/handle utilities, and navigation helpers.
   - These packages reduce duplication and define the “horizontal” platform layer beneath app-specific features.

13. **Key frontend feature areas**
   - The web app is organized around document management, spaces management, favorites/recent views, user settings, and the split-pane tab workspace.
   - The layout layer includes sidebar navigation, document tree, space switcher, search, tabs, and panes, which together form the main shell around the editor.
   - Most screens are data-driven through query hooks in `apps/web/src/queries`, keeping fetching logic separate from presentation.

14. **Operational and build boundaries**
   - Turborepo orchestrates builds, type-checking, linting, and task caching across all apps/packages.
   - Docker Compose and a dedicated backend Dockerfile support containerized deployment, with the backend/API and web app exposed as separate services.
   - Database migration scripts and CI workflow files show that schema evolution and release automation are part of the repo’s operational architecture.

Main entry points: [`apps/web`](https://github.com/teamcoderz/wordyme/tree/main/apps/web) (Web app), [`apps/backend/src`](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src) (Backend API), [`apps/backend/src/services`](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/services) (Services), [`packages/editor`](https://github.com/teamcoderz/wordyme/tree/main/packages/editor) (Editor package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
end

subgraph group_backend["Backend"]
  node_apps_backend["Backend API<br/>express server"]
  node_backend_routes["HTTP routes<br/>api surface"]
  node_backend_services["Services<br/>business logic"]
  node_backend_models[("Models")]
  node_backend_lib["Server lib<br/>foundation"]
  node_backend_schemas["Schemas<br/>validation contracts"]
  node_backend_db[("Migrations<br/>drizzle/sqlite")]
  node_backend_storage[("Storage<br/>filesystem assets")]
end

subgraph group_web["Web"]
  node_apps_web["Web app<br/>vite-react client"]
  node_web_routes["Routes<br/>router boundaries"]
  node_web_layout["App shell<br/>navigation/ui shell"]
  node_web_documents["Documents UI<br/>feature screens"]
  node_web_settings["Settings UI<br/>feature screens"]
  node_web_home_spaces["Home & spaces<br/>dashboard features"]
  node_web_state[("Client state<br/>zustand stores")]
  node_web_queries["Queries<br/>data fetching"]
  node_web_realtime(("Realtime client<br/>socket provider"))
  node_web_sdk_use["SDK usage<br/>client contract<br/>[useServices.ts]"]
end

subgraph group_packages["Shared Packages"]
  node_packages_editor["Editor package<br/>lexical editor"]
  node_packages_sdk["SDK<br/>api client"]
  node_packages_ui["UI kit<br/>component library"]
  node_packages_types["Shared types<br/>domain contracts"]
  node_packages_shared["Shared utils<br/>pure helpers"]
  node_packages_lib["Core lib<br/>utility core"]
end

node_apps_web -->|"renders"| node_web_routes
node_apps_web -->|"composes"| node_web_layout
node_apps_web -->|"hosts"| node_web_documents
node_apps_web -->|"hosts"| node_web_settings
node_apps_web -->|"hosts"| node_web_home_spaces
node_apps_web -->|"uses"| node_web_state
node_apps_web -->|"fetches via"| node_web_queries
node_apps_web -->|"syncs via"| node_web_realtime
node_web_documents -->|"embeds"| node_packages_editor
node_web_layout -->|"uses"| node_packages_ui
node_web_queries -->|"calls"| node_packages_sdk
node_web_documents -->|"shares"| node_packages_types
node_web_state -->|"shares"| node_packages_types
node_apps_backend -->|"exposes"| node_backend_routes
node_apps_backend -->|"delegates to"| node_backend_services
node_apps_backend -->|"persists through"| node_backend_models
node_apps_backend -->|"bootstraps with"| node_backend_lib
node_apps_backend -->|"validates with"| node_backend_schemas
node_apps_backend -->|"migrates with"| node_backend_db
node_apps_backend -->|"stores files in"| node_backend_storage
node_backend_routes -->|"orchestrates"| node_backend_services
node_backend_services -->|"reads/writes"| node_backend_models
node_backend_services -->|"uses"| node_backend_lib
node_backend_services -->|"checks"| node_backend_schemas
node_backend_services -->|"supports"| node_packages_editor
node_packages_sdk -->|"typed by"| node_packages_types
node_packages_editor -->|"builds on"| node_packages_ui
node_packages_editor -->|"uses"| node_packages_shared
node_packages_editor -->|"uses"| node_packages_lib

click node_apps_web "https://github.com/teamcoderz/wordyme/tree/main/apps/web"
click node_web_routes "https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/routes"
click node_web_layout "https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/components/Layout"
click node_web_documents "https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/components/documents"
click node_web_settings "https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/components/Settings"
click node_web_home_spaces "https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/components/Home"
click node_web_state "https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/store"
click node_web_queries "https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/queries"
click node_web_realtime "https://github.com/teamcoderz/wordyme/blob/main/apps/web/src/providers/RealtimeProvider.tsx"
click node_web_sdk_use "https://github.com/teamcoderz/wordyme/blob/main/apps/web/src/components/documents/useServices.ts"
click node_apps_backend "https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src"
click node_backend_routes "https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/routes"
click node_backend_services "https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/services"
click node_backend_models "https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/models"
click node_backend_lib "https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/lib"
click node_backend_schemas "https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/schemas"
click node_backend_db "https://github.com/teamcoderz/wordyme/tree/main/apps/backend/drizzle"
click node_backend_storage "https://github.com/teamcoderz/wordyme/tree/main/apps/backend/storage"
click node_packages_editor "https://github.com/teamcoderz/wordyme/tree/main/packages/editor"
click node_packages_sdk "https://github.com/teamcoderz/wordyme/tree/main/packages/sdk"
click node_packages_ui "https://github.com/teamcoderz/wordyme/tree/main/packages/ui"
click node_packages_types "https://github.com/teamcoderz/wordyme/tree/main/packages/types"
click node_packages_shared "https://github.com/teamcoderz/wordyme/tree/main/packages/shared"
click node_packages_lib "https://github.com/teamcoderz/wordyme/tree/main/packages/lib"

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_apps_backend,node_backend_routes,node_backend_services,node_backend_models,node_backend_lib,node_backend_schemas,node_backend_db,node_backend_storage toneAmber
class node_apps_web,node_web_routes,node_web_layout,node_web_documents,node_web_settings,node_web_home_spaces,node_web_state,node_web_queries,node_web_realtime,node_web_sdk_use toneMint
class node_packages_editor,node_packages_sdk,node_packages_ui,node_packages_types,node_packages_shared,node_packages_lib toneRose
```

## Components

### Backend

API, data, and server-side business logic

- [Backend API](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src): express server · System of record for auth, documents, revisions, favorites, settings, and storage · `apps/backend/src`
- [HTTP routes](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/routes): api surface · Auth state, documents, revisions, favorites, editor settings, storage, and health endpoints · `apps/backend/src/routes`
- [Services](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/services): business logic · Document lifecycle, access control, attachments, images, search, revisions, and operations · `apps/backend/src/services`
- [Models](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/models): db models · Drizzle-backed persistence models for documents, users, revisions, views, favorites, and search index · `apps/backend/src/models`
- [Server lib](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/lib): foundation · Auth, database, docs helpers, sockets, and storage plumbing · `apps/backend/src/lib`
- [Schemas](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/src/schemas): validation contracts · Zod request and response schemas for routes and services · `apps/backend/src/schemas`
- [Migrations](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/drizzle): drizzle/sqlite · SQLite/libSQL schema evolution and journal snapshots · `apps/backend/drizzle`
- [Storage](https://github.com/teamcoderz/wordyme/tree/main/apps/backend/storage): filesystem assets · Local storage area for binary assets and persisted files · `apps/backend/storage`

### Web

React client shell and routed UI

- [Web app](https://github.com/teamcoderz/wordyme/tree/main/apps/web): vite-react client · React 19 frontend with routed document workspace and app shell · `apps/web`
- [Routes](https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/routes): router boundaries · TanStack Router trees for authed and unauthed navigation · `apps/web/src/routes`
- [App shell](https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/components/Layout): navigation/ui shell · Sidebar, tabs, split panes, search, and document tree layout · `apps/web/src/components/Layout`
- [Documents UI](https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/components/documents): feature screens · Edit, view, manage, sidebar, attachments, and revision history screens · `apps/web/src/components/documents`
- [Settings UI](https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/components/Settings): feature screens · Profile, preferences, roles, users, and avatar management screens · `apps/web/src/components/Settings`
- [Home & spaces](https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/components/Home): dashboard features · Favorites, recents, and space management views · `apps/web/src/components/Home`
- [Client state](https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/store): zustand stores · Tab, UI, user, and editor ephemeral state · `apps/web/src/store`
- [Queries](https://github.com/teamcoderz/wordyme/tree/main/apps/web/src/queries): data fetching · TanStack Query hooks, cache helpers, and query keys · `apps/web/src/queries`
- [Realtime client](https://github.com/teamcoderz/wordyme/blob/main/apps/web/src/providers/RealtimeProvider.tsx): socket provider · WebSocket synchronization provider for live document state · `apps/web/src/providers/RealtimeProvider.tsx`
- [SDK usage](https://github.com/teamcoderz/wordyme/blob/main/apps/web/src/components/documents/useServices.ts): client contract · Web features consume backend APIs through the shared SDK and types · `apps/web/src/components/documents/useServices.ts`

### Shared Packages

Reusable editor, SDK, UI, and core utilities

- [Editor package](https://github.com/teamcoderz/wordyme/tree/main/packages/editor): lexical editor · Standalone editor/viewer with custom nodes, plugins, dialogs, and rendering utilities · `packages/editor`
- [SDK](https://github.com/teamcoderz/wordyme/tree/main/packages/sdk): api client · Shared backend client for documents, revisions, storage, favorites, settings, and realtime · `packages/sdk`
- [UI kit](https://github.com/teamcoderz/wordyme/tree/main/packages/ui): component library · Reusable design system components, layout primitives, and theme controls · `packages/ui`
- [Shared types](https://github.com/teamcoderz/wordyme/tree/main/packages/types): domain contracts · Common domain types for documents, revisions, spaces, users, tabs, and UI · `packages/types`
- [Shared utils](https://github.com/teamcoderz/wordyme/tree/main/packages/shared): pure helpers · Cross-cutting utilities for checksums, debounce, environment, keyboard, navigation, and UUIDs · `packages/shared`
- [Core lib](https://github.com/teamcoderz/wordyme/tree/main/packages/lib): utility core · Filename, handle, id, position, and tree helpers shared across the workspace · `packages/lib`

## Connections

- Web app → Routes: renders · Bootstraps routed application shell
- Web app → App shell: composes · Main navigation and workspace layout
- Web app → Documents UI: hosts · Document editing, viewing, and management UI
- Web app → Settings UI: hosts · User and admin settings UI
- Web app → Home & spaces: hosts · Home dashboard and space screens
- Web app → Client state: uses · Local UI and tab state
- Web app → Queries: fetches via · Server state and cache management
- Web app → Realtime client: syncs via · Live document and editor updates
- Documents UI → Editor package: embeds · Editing and viewing surface
- App shell → UI kit: uses · Shared UI primitives
- Queries → SDK: calls · Backend contract access
- Documents UI → Shared types: shares · Document and revision domain types
- Client state → Shared types: shares · Tabs, UI, and user state shapes
- Backend API → HTTP routes: exposes · HTTP API surface
- Backend API → Services: delegates to · Feature business logic
- Backend API → Models: persists through · Database-backed models
- Backend API → Server lib: bootstraps with · Auth, DB, sockets, docs, storage
- Backend API → Schemas: validates with · Request and response contracts
- Backend API → Migrations: migrates with · Schema evolution files
- Backend API → Storage: stores files in · Binary assets and local persistence
- HTTP routes → Services: orchestrates · Route handlers call service layer
- Services → Models: reads/writes · Business logic persists through models
- Services → Server lib: uses · Auth, docs, storage, sockets, DB helpers
- Services → Schemas: checks · Domain validation and payload shape
- Services → Editor package: supports · Document content, attachments, and rendering conventions
- SDK → Shared types: typed by · Shared domain contracts
- Editor package → UI kit: builds on · Editor chrome and controls
- Editor package → Shared utils: uses · Utility helpers and common behavior
- Editor package → Core lib: uses · Tree and identifier helpers
