# rashal10/decodoc architecture

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

- Interactive diagram: https://gitdiagram.com/rashal10/decodoc
- Repository: https://github.com/rashal10/decodoc

## Overview

1. **Overall shape**
   - DecoDoc is a split-stack monorepo with three main codebases: `client/` for the React UI, `server/` for the Express API and analysis engine, and `shared/` for cross-cutting types/utilities.
   - The system is centered on a paper-analysis workflow: a user supplies an arXiv ID, DOI, abstract, or PDF; the backend resolves the paper, runs analysis, caches results in Postgres, and the frontend renders structured outputs.

2. **Frontend application boundary**
   - The client is a Vite + React + TypeScript app with Tailwind and a sizable component library under `client/src/components/`.
   - Routing/pages are separated into `HomePage`, `LibraryPage`, `PaperDetailPage`, `SignInPage`, and `SignUpPage`, with `AppShell` and layout components handling the persistent frame.
   - The UI is split between marketing/discovery surfaces (`home/`) and authenticated product surfaces (`library/`, `paper/`, `auth/`).

3. **User interaction flow**
   - The primary entry point is the home experience, where users submit paper identifiers or upload PDFs.
   - Analysis results are then displayed through paper-specific views, including tabs, badges, and analysis-specific panels.
   - The `PaperDetailPage` is the likely hub that fetches cached analysis, shows metadata, and renders the various result sections.

4. **Client-side state and persistence**
   - The client keeps some user data locally via IndexedDB and `localStorage`, specifically for recents and bookmarks as noted in the README.
   - This creates a boundary between ephemeral viewing state on the browser and durable analysis state stored on the server.
   - PDF text extraction happens in the browser before upload, so the backend receives text rather than raw PDF parsing responsibility in the common path.

5. **Authentication and session handling**
   - Authentication is handled in the client with a dedicated auth context and auth-related components, plus server-side JWT support.
   - The frontend has sign-in/sign-up flows and a “login required” modal, indicating optional anonymous usage with gated features for library/bookmarks.
   - The backend exposes auth routes and JWT/password utilities, suggesting credential-based auth with server-issued tokens rather than third-party SSO.

6. **Backend API layer**
   - The server is an Express API split across `index.ts`, `routes.ts`, and specialized route modules such as `auth-routes.ts`.
   - Public endpoints include analysis, PDF upload, paper lookup, usage/quota status, and bookmarks.
   - The API acts as the boundary for all persistence, quota enforcement, and LLM orchestration; the client never talks directly to databases or model providers.

7. **Analysis pipeline**
   - The analysis subsystem is the core backend capability: it validates requested analysis payloads, computes paper identity, extracts or enriches citations and sources, and generates structured output.
   - Files like `analysisValidation.ts`, `paperIdentity.ts`, `citations.ts`, `sources.ts`, and `similarity.ts` indicate a pipeline that normalizes inputs, finds canonical paper metadata, and assembles supporting context.
   - `analysisCache.ts` implies the server caches completed analyses by paper ID to avoid rerunning expensive model calls.

8. **LLM and embeddings abstraction**
   - LLM access is abstracted under `server/src/llm/`, with provider adapters for Groq, OpenAI-compatible endpoints, and Gemini-related functionality.
   - The README states Groq is primary, OpenRouter is fallback, and Gemini is used for embeddings, so model selection is an operational concern rather than a frontend concern.
   - This provider layer isolates vendor-specific differences from the rest of the analysis logic.

9. **Database and schema management**
   - Postgres is the persistence layer, accessed through Drizzle ORM and migration files under `server/drizzle/`.
   - The server includes schema definitions, migration tooling, and initialization logic, which means database shape is versioned and managed as part of the app.
   - Cached analyses, users, bookmarks, and usage/quota state are all likely persisted here, with Postgres serving as the durable source of truth.

10. **Quota and access control**
   - The backend enforces usage limits through a quota subsystem, with anonymous and signed-in users receiving different daily allowances.
   - This means authentication affects not only access to library features but also analysis capacity.
   - The `/api/me/usage` endpoint acts as the visibility layer for client-side quota messaging.

11. **Paper metadata and external sources**
   - The system integrates external scholarly sources: arXiv, Crossref, and Semantic Scholar.
   - These sources are used to resolve identifiers, fetch metadata, and enrich analysis results with canonical paper details and citation context.
   - This external-source layer sits between user input and analysis output, making paper identity resolution a key architectural step.

12. **Deployment and runtime boundaries**
   - The repo is designed for a split deployment: frontend on Vercel, backend on Render or Railway, with Docker support for local or containerized server deployment.
   - The client is built with a baked-in `VITE_API_BASE_URL`, so frontend and API are loosely coupled at runtime but tightly coupled at build time through environment configuration.
   - The server boots with database migrations and exposes a health endpoint, which makes it the operational unit for API + Postgres deployment.

13. **Shared code and test surface**
   - The `shared/` package suggests common code reused by both client and server, likely for shared types, schemas, or helpers that need to stay in sync.
   - Both client and server contain tests, with backend tests covering validation, citations, config, DB, and source logic, reflecting the importance of correctness in analysis and persistence.
   - This repo is therefore not just a UI plus API, but a coordinated product with shared contracts and substantial backend domain logic.

Main entry points: [`server/src/analysisValidation.ts`](https://github.com/rashal10/decodoc/blob/main/server/src/analysisValidation.ts) (Analysis pipeline), [`server/src/routes.ts`](https://github.com/rashal10/decodoc/blob/main/server/src/routes.ts) (API routes), [`client/src/layouts/AppShell.tsx`](https://github.com/rashal10/decodoc/blob/main/client/src/layouts/AppShell.tsx) (App shell), [`client/src/lib/api.ts`](https://github.com/rashal10/decodoc/blob/main/client/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["client"]
  node_client_pages_home["Home page<br/>React page<br/>[HomePage.tsx]"]
  node_client_pages_paper["Paper detail<br/>React page"]
  node_client_pages_library["Library<br/>React page<br/>[LibraryPage.tsx]"]
  node_client_pages_auth["Sign in/up<br/>React pages<br/>[SignInPage.tsx]"]
  node_client_layout_shell["App shell<br/>Layout<br/>[AppShell.tsx]"]
  node_client_components_home["Home UI<br/>UI components<br/>[AnalyzePanel.tsx]"]
  node_client_components_paper["Paper UI<br/>UI components<br/>[ResultsTabs.tsx]"]
  node_client_components_auth["Auth UI<br/>UI components<br/>[AuthShell.tsx]"]
  node_client_components_library["Library card<br/>UI component<br/>[PaperCard.tsx]"]
  node_client_lib_api["API client<br/>[api.ts]"]
  node_client_lib_auth["Auth state<br/>Client auth<br/>[auth-context.tsx]"]
  node_client_lib_storage["Local storage<br/>Browser persistence<br/>[storage.ts]"]
  node_client_lib_pdf["PDF extract<br/>Browser preprocessing<br/>[pdf.ts]"]
end

subgraph group_server["server"]
  node_server_entry["API entry<br/>Express bootstrap<br/>[index.ts]"]
  node_server_routes["API routes<br/>HTTP routing<br/>[routes.ts]"]
  node_server_auth_routes["Auth routes<br/>HTTP routing<br/>[auth-routes.ts]"]
  node_server_analysis["Analysis pipeline<br/>Domain pipeline"]
  node_server_llm["LLM adapters<br/>Model abstraction<br/>[index.ts]"]
  node_server_db[("Postgres layer<br/>Persistence<br/>[db.ts]")]
  node_server_auth["Auth + quota<br/>Security and limits<br/>[quota.ts]"]
end

subgraph group_shared["shared"]
  node_shared_pkg["Shared code<br/>Common package<br/>[index.ts]"]
end

node_client_pages_home --> node_client_components_home
node_client_pages_paper --> node_client_components_paper
node_client_pages_library --> node_client_components_library
node_client_pages_auth --> node_client_components_auth
node_client_layout_shell --> node_client_pages_home
node_client_layout_shell --> node_client_pages_paper
node_client_layout_shell --> node_client_pages_library
node_client_lib_pdf --> node_client_components_home
node_client_lib_storage --> node_client_pages_library
node_client_lib_auth --> node_client_pages_auth
node_client_lib_api --> node_server_routes
node_client_lib_api --> node_server_auth_routes
node_server_entry --> node_server_routes
node_server_entry --> node_server_auth_routes
node_server_routes --> node_server_analysis
node_server_routes --> node_server_auth
node_server_auth_routes --> node_server_auth
node_server_analysis --> node_server_llm
node_server_analysis --> node_server_db
node_server_auth --> node_server_db
node_server_analysis --> node_shared_pkg
node_client_lib_api --> node_shared_pkg

click node_client_pages_home "https://github.com/rashal10/decodoc/blob/main/client/src/pages/HomePage.tsx"
click node_client_pages_paper "https://github.com/rashal10/decodoc/blob/main/client/src/pages/PaperDetailPage.tsx"
click node_client_pages_library "https://github.com/rashal10/decodoc/blob/main/client/src/pages/LibraryPage.tsx"
click node_client_pages_auth "https://github.com/rashal10/decodoc/blob/main/client/src/pages/SignInPage.tsx"
click node_client_layout_shell "https://github.com/rashal10/decodoc/blob/main/client/src/layouts/AppShell.tsx"
click node_client_components_home "https://github.com/rashal10/decodoc/blob/main/client/src/components/home/AnalyzePanel.tsx"
click node_client_components_paper "https://github.com/rashal10/decodoc/blob/main/client/src/components/paper/ResultsTabs.tsx"
click node_client_components_auth "https://github.com/rashal10/decodoc/blob/main/client/src/components/auth/AuthShell.tsx"
click node_client_components_library "https://github.com/rashal10/decodoc/blob/main/client/src/components/library/PaperCard.tsx"
click node_client_lib_api "https://github.com/rashal10/decodoc/blob/main/client/src/lib/api.ts"
click node_client_lib_auth "https://github.com/rashal10/decodoc/blob/main/client/src/lib/auth-context.tsx"
click node_client_lib_storage "https://github.com/rashal10/decodoc/blob/main/client/src/lib/storage.ts"
click node_client_lib_pdf "https://github.com/rashal10/decodoc/blob/main/client/src/lib/pdf.ts"
click node_server_entry "https://github.com/rashal10/decodoc/blob/main/server/src/index.ts"
click node_server_routes "https://github.com/rashal10/decodoc/blob/main/server/src/routes.ts"
click node_server_auth_routes "https://github.com/rashal10/decodoc/blob/main/server/src/auth-routes.ts"
click node_server_analysis "https://github.com/rashal10/decodoc/blob/main/server/src/analysisValidation.ts"
click node_server_llm "https://github.com/rashal10/decodoc/blob/main/server/src/llm/index.ts"
click node_server_db "https://github.com/rashal10/decodoc/blob/main/server/src/db.ts"
click node_server_auth "https://github.com/rashal10/decodoc/blob/main/server/src/quota.ts"
click node_shared_pkg "https://github.com/rashal10/decodoc/blob/main/shared/src/index.ts"

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_client_pages_home,node_client_pages_paper,node_client_pages_library,node_client_pages_auth,node_client_layout_shell,node_client_components_home,node_client_components_paper,node_client_components_auth,node_client_components_library,node_client_lib_api,node_client_lib_auth,node_client_lib_storage,node_client_lib_pdf toneBlue
class node_server_entry,node_server_routes,node_server_auth_routes,node_server_analysis,node_server_llm,node_server_db,node_server_auth toneAmber
class node_shared_pkg toneMint
```

## Components

### client

React frontend and browser-side state

- [Home page](https://github.com/rashal10/decodoc/blob/main/client/src/pages/HomePage.tsx): React page · Landing experience for submitting paper IDs or PDFs · `client/src/pages/HomePage.tsx`
- [Paper detail](https://github.com/rashal10/decodoc/blob/main/client/src/pages/PaperDetailPage.tsx): React page · Primary paper results view with cached analysis and metadata · `client/src/pages/PaperDetailPage.tsx`
- [Library](https://github.com/rashal10/decodoc/blob/main/client/src/pages/LibraryPage.tsx): React page · Authenticated list of saved papers and recents · `client/src/pages/LibraryPage.tsx`
- [Sign in/up](https://github.com/rashal10/decodoc/blob/main/client/src/pages/SignInPage.tsx): React pages · Credential-based authentication entry points · `client/src/pages/SignInPage.tsx`
- [App shell](https://github.com/rashal10/decodoc/blob/main/client/src/layouts/AppShell.tsx): Layout · Persistent site frame and navigation chrome · `client/src/layouts/AppShell.tsx`
- [Home UI](https://github.com/rashal10/decodoc/blob/main/client/src/components/home/AnalyzePanel.tsx): UI components · Hero, feature, and analyze input surfaces · `client/src/components/home/AnalyzePanel.tsx`
- [Paper UI](https://github.com/rashal10/decodoc/blob/main/client/src/components/paper/ResultsTabs.tsx): UI components · Analysis tabs and paper-specific badges/panels · `client/src/components/paper/ResultsTabs.tsx`
- [Auth UI](https://github.com/rashal10/decodoc/blob/main/client/src/components/auth/AuthShell.tsx): UI components · Auth shell, forms, and gated-access modal · `client/src/components/auth/AuthShell.tsx`
- [Library card](https://github.com/rashal10/decodoc/blob/main/client/src/components/library/PaperCard.tsx): UI component · Saved paper card used in the library view · `client/src/components/library/PaperCard.tsx`
- [API client](https://github.com/rashal10/decodoc/blob/main/client/src/lib/api.ts): Browser API client · Typed client calls to the backend API · `client/src/lib/api.ts`
- [Auth state](https://github.com/rashal10/decodoc/blob/main/client/src/lib/auth-context.tsx): Client auth · Auth context, nav helpers, and login-required behavior · `client/src/lib/auth-context.tsx`
- [Local storage](https://github.com/rashal10/decodoc/blob/main/client/src/lib/storage.ts): Browser persistence · IndexedDB/localStorage for recents and bookmarks · `client/src/lib/storage.ts`
- [PDF extract](https://github.com/rashal10/decodoc/blob/main/client/src/lib/pdf.ts): Browser preprocessing · Client-side text extraction before upload · `client/src/lib/pdf.ts`

### server

Express API, analysis engine, and persistence

- [API entry](https://github.com/rashal10/decodoc/blob/main/server/src/index.ts): Express bootstrap · Starts the server and wires middleware/routes · `server/src/index.ts`
- [API routes](https://github.com/rashal10/decodoc/blob/main/server/src/routes.ts): HTTP routing · Main request routing for analysis, lookup, quota, and bookmarks · `server/src/routes.ts`
- [Auth routes](https://github.com/rashal10/decodoc/blob/main/server/src/auth-routes.ts): HTTP routing · Sign-in, sign-up, and auth-specific endpoints · `server/src/auth-routes.ts`
- [Analysis pipeline](https://github.com/rashal10/decodoc/blob/main/server/src/analysisValidation.ts): Domain pipeline · Validates input, resolves paper identity, enriches sources, and caches results · `server/src/analysisValidation.ts`
- [LLM adapters](https://github.com/rashal10/decodoc/blob/main/server/src/llm/index.ts): Model abstraction · Provider layer for Groq/OpenAI-compatible/Gemini calls · `server/src/llm/index.ts`
- [Postgres layer](https://github.com/rashal10/decodoc/blob/main/server/src/db.ts): Persistence · Database schema, migrations, and initialization · `server/src/db.ts`
- [Auth + quota](https://github.com/rashal10/decodoc/blob/main/server/src/quota.ts): Security and limits · JWT/password handling and usage enforcement · `server/src/quota.ts`

### shared

Cross-cutting types and helpers

- [Shared code](https://github.com/rashal10/decodoc/blob/main/shared/src/index.ts): Common package · Types and helpers used by both client and server · `shared/src/index.ts`

## Connections

- Home page → Home UI: Composes the landing and submit experience
- Paper detail → Paper UI: Renders analysis sections and paper metadata
- Library → Library card: Shows saved papers in list form
- Sign in/up → Auth UI: Uses dedicated auth presentation
- App shell → Home page: Frames the public home route
- App shell → Paper detail: Frames the paper detail route
- App shell → Library: Frames the library route
- PDF extract → Home UI: Extracts PDF text before submission
- Local storage → Library: Backs recents and bookmarks
- Auth state → Sign in/up: Drives sign-in/sign-up state
- API client → API routes: Calls the backend API surface
- API client → Auth routes: Calls authentication endpoints
- API entry → API routes: Mounts main API routes
- API entry → Auth routes: Mounts auth routes
- API routes → Analysis pipeline: Dispatches analysis and paper lookup requests
- API routes → Auth + quota: Checks quota and access limits
- Auth routes → Auth + quota: Handles credential flow and JWT issuance
- Analysis pipeline → LLM adapters: Invokes model providers for structured analysis
- Analysis pipeline → Postgres layer: Reads and writes cached analysis and metadata
- Auth + quota → Postgres layer: Persists users and usage state
- Analysis pipeline → Shared code: Shares contracts and data shapes
- API client → Shared code: Consumes shared response types