rashal10/decodoc

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.