How teamcoderz/wordyme works
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: web Web app · src Backend API · services Services · editor Editor package
Components 24
Backend
API, data, and server-side business logic
- Backend API · System of record for auth, documents, revisions, favorites, settings, and storage
apps/backend/src - HTTP routes · Auth state, documents, revisions, favorites, editor settings, storage, and health endpoints
apps/backend/src/routes - Services · Document lifecycle, access control, attachments, images, search, revisions, and operations
apps/backend/src/services - Models · Drizzle-backed persistence models for documents, users, revisions, views, favorites, and search index
apps/backend/src/models - Server lib · Auth, database, docs helpers, sockets, and storage plumbing
apps/backend/src/lib - Schemas · Zod request and response schemas for routes and services
apps/backend/src/schemas - Migrations · SQLite/libSQL schema evolution and journal snapshots
apps/backend/drizzle - Storage · Local storage area for binary assets and persisted files
apps/backend/storage
Web
React client shell and routed UI
- Web app · React 19 frontend with routed document workspace and app shell
apps/web - Routes · TanStack Router trees for authed and unauthed navigation
apps/web/src/routes - App shell · Sidebar, tabs, split panes, search, and document tree layout
apps/web/src/components/Layout - Documents UI · Edit, view, manage, sidebar, attachments, and revision history screens
apps/web/src/components/documents - Settings UI · Profile, preferences, roles, users, and avatar management screens
apps/web/src/components/Settings - Home & spaces · Favorites, recents, and space management views
apps/web/src/components/Home - Client state · Tab, UI, user, and editor ephemeral state
apps/web/src/store - Queries · TanStack Query hooks, cache helpers, and query keys
apps/web/src/queries - Realtime client · WebSocket synchronization provider for live document state
apps/web/src/providers/RealtimeProvider.tsx - SDK usage · 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 · Standalone editor/viewer with custom nodes, plugins, dialogs, and rendering utilities
packages/editor - SDK · Shared backend client for documents, revisions, storage, favorites, settings, and realtime
packages/sdk - UI kit · Reusable design system components, layout primitives, and theme controls
packages/ui - Shared types · Common domain types for documents, revisions, spaces, users, tabs, and UI
packages/types - Shared utils · Cross-cutting utilities for checksums, debounce, environment, keyboard, navigation, and UUIDs
packages/shared - Core lib · Filename, handle, id, position, and tree helpers shared across the workspace
packages/lib
Connections 29
- 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