# Project export: ResearchOS This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: OpenAI Build Week - Tagline: The operating system for modern research, bringing literature review, citation analysis, gap discovery, journal matching, and AI-powered insights into one workspace. - Devpost: https://devpost.com/software/researchos - GitHub: https://github.com/lordcerebrimbor/researchos-core - Video: https://www.youtube.com/embed/Usss2qGZOkY?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Team: 1 GitHub contributor(s) — lordcerebrimbor (39 commits) ## Devpost submission (written by the team) ### Overview ResearchOS is an AI-powered, local-first research workspace built to simplify the modern research process. Researchers often juggle multiple disconnected tools for reading papers, taking notes, managing citations, organizing literature, and using AI assistants. This fragmented workflow creates unnecessary context switching and slows down scientific discovery. ResearchOS brings these essential workflows together into one integrated application. It combines literature management, intelligent PDF reading, AI-powered paper understanding, citation analysis, knowledge graph visualization, research gap discovery, journal recommendations, and project organization in a unified workspace. By keeping research data local while integrating powerful AI capabilities, ResearchOS enables researchers to work more efficiently without compromising privacy or ownership of their work. Our vision is to provide a single operating system for research that allows students, academics, and professionals to spend less time managing information and more time generating meaningful insights. The idea for ResearchOS came from experiencing the fragmented nature of academic research firsthand. Reading papers, organizing notes, managing references, discovering related work, and using AI assistants often require switching between numerous applications and browser tabs. While AI has made individual research tasks easier, there is still no unified workspace where the entire research workflow exists in one place. We wanted to build a platform that removes this friction by integrating every stage of the research process into a single, AI-native environment. ResearchOS provides researchers with an end-to-end research workspace that includes: Literature management and organization Intelligent PDF reading and annotation AI-assisted paper understanding Citation analysis Interactive knowledge graph visualization Research gap discovery Journal recommendation support Research project organization Local-first document management Instead of treating these as separate tools, ResearchOS connects them into a seamless workflow that keeps knowledge organized and accessible throughout the research lifecycle. ResearchOS was built using a modern full-stack architecture designed for performance, scalability, and maintainability. Frontend Next.js React TypeScript Tailwind CSS Backend Next.js API Routes Prisma ORM SQLite AI & Research Infrastructure OpenAlex API GPT-5 via OpenAI Local-first document storage Knowledge graph generation Intelligent metadata extraction Development was accelerated using OpenAI Codex for architecture planning, implementation, refactoring, debugging, and rapid iteration. Throughout development, we focused on creating modular, production-ready components rather than isolated prototypes. One of the biggest challenges was designing a research workflow that felt unified instead of simply combining multiple independent tools. Integrating literature management, AI-powered analysis, citation workflows, and visualization into a cohesive user experience required several iterations of both the architecture and interface. Another challenge was balancing powerful AI features with a local-first approach. We wanted users to benefit from modern AI capabilities while maintaining ownership and control over their research data. Finally, ensuring smooth interaction between multiple data sources, asynchronous AI processing, and responsive user interfaces required careful engineering throughout the project. We're particularly proud that ResearchOS evolved beyond a collection of utilities into a cohesive research platform. Some highlights include: A polished and modern user interface Integrated literature management AI-assisted research workflows Interactive knowledge graph visualization Citation intelligence Local-first architecture Modular and scalable codebase Production-quality demonstration Rather than solving a single research problem, ResearchOS demonstrates how AI can support the complete research lifecycle. Building ResearchOS reinforced the importance of designing software around real user workflows instead of individual features. We also learned how thoughtful integration of AI can significantly improve productivity without overwhelming users. The project strengthened our understanding of modern full-stack development, AI-assisted software engineering, modular architecture, and designing products that balance usability, performance, and privacy. ResearchOS is only the beginning. Our roadmap includes: Multi-agent AI research assistants Semantic search across personal research libraries Automated literature review generation Collaborative research workspaces Advanced citation network exploration Plugin ecosystem Optional cloud synchronization while preserving local-first principles Deeper integrations with academic databases and publishing platforms Our long-term vision is for ResearchOS to become the operating system researchers use every day—from discovering ideas to publishing new knowledge. ## README (from the GitHub repository)
# ResearchOS Core ### The offline-first workspace for turning literature into understanding. Discover trusted research, capture evidence in context, reveal connections, and produce defensible synthesis—without losing the thread of your thinking. [![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org/) [![React](https://img.shields.io/badge/React-19-149eca?logo=react)](https://react.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Prisma](https://img.shields.io/badge/Prisma-7-2D3748?logo=prisma)](https://www.prisma.io/) [![Offline](https://img.shields.io/badge/analysis-local--only-0e7490)](#offline-analysis-engine) [Explore the demo](#quick-start) · [Architecture](#architecture) · [Contributing](#contributing)
--- ## Research, without the fragmented workflow ResearchOS Core is a full research environment for people who need more than a reference manager and more rigor than a chat window. It brings discovery, reading, annotation, deterministic analysis, graph exploration, and exports into one focused workspace—without a hosted LLM or cloud AI account. > **Built around evidence.** AI outputs are designed as durable, source-linked artifacts—not opaque answers detached from the research that supports them. ## What you can do | | Capability | What it helps you achieve | | --- | --------------------------- | -------------------------------------------------------------------------- | | 🔎 | **Discover & import** | Search scholarly work and build a local, source-aware paper library. | | 📖 | **Read in context** | Open PDFs, track progress, create page-linked highlights, and write notes. | | ✦ | **Ask grounded questions** | Use AI-assisted research conversations tied to workspace evidence. | | ◌ | **See the research graph** | Explore relationships among papers, concepts, notes, and citations. | | ≡ | **Synthesize literature** | Turn selected evidence into structured literature reviews. | | ◈ | **Delegate research tasks** | Launch and inspect research-agent plans, steps, and artifacts. | | ↓ | **Ship results** | Export citation-ready research in portable formats. | ## Research workflow ```mermaid flowchart LR A["Ask a research question"] --> B["Discover papers"] B --> C["Import & normalize"] C --> D["Read PDF"] D --> E["Highlight evidence"] E --> F["Write linked notes"] F --> G["Ask grounded AI"] G --> H["Explore knowledge graph"] H --> I["Generate literature review"] I --> J["Export results"] classDef primary fill:#0e7490,stroke:#155e75,color:#fff; classDef artifact fill:#ecfeff,stroke:#0891b2,color:#164e63; class A,J primary; class B,C,D,E,F,G,H,I artifact; ``` Every step leaves behind reusable research artifacts. Notes retain their evidence, AI results retain their provenance, and graph connections remain explainable. ## Screenshots | Landing | Workspace | | ------------------------------------------------ | ------------------------------------------------------ | | ![ResearchOS landing page](docs/assets/landing.png) | ![ResearchOS workspace](docs/assets/workspace.png) | | Research library | Knowledge graph | | -------------------------------------------------- | ---------------------------------------------------------------- | | ![ResearchOS library](docs/assets/library.png) | ![ResearchOS knowledge graph](docs/assets/knowledge-graph.png) | | Research insights | Project workspace | | -------------------------------------------------- | ---------------------------------------------------- | | ![ResearchOS research themes](docs/assets/themes.png) | ![ResearchOS project workspace](docs/assets/project.png) | | Reading & evidence | | ---------------------------------------------- | | ![ResearchOS reader](docs/assets/reader.png) | ## Demo A full 1920×1080 product walkthrough — landing, demo workspace, library, knowledge graph, insights, projects, and the PDF reader — is available at [docs/demo/researchos-demo.webm](docs/demo/researchos-demo.webm). Regenerate the screenshots and video at any time against a running server: ```bash npm run build && npx next start # serve the production app on :3000 npm run demo:capture # record docs/assets/*.png + docs/demo/researchos-demo.webm ``` ## Installation ### Prerequisites - Node.js 20 or later - npm 10 or later ### Local setup From a fresh clone, the complete local database setup is one command: ```bash npm run bootstrap ``` `bootstrap` installs dependencies, creates `.env` from `.env.example` when it is absent, generates Prisma Client, and applies the local SQLite migrations. It never overwrites an existing `.env`. To run the required commands individually instead, no manual environment-file copy is needed: ```bash git clone cd researchos npm install npx prisma generate npx prisma migrate dev npm run dev ``` Open [http://localhost:3000](http://localhost:3000) to start exploring. ### Environment Configuration is validated at startup and kept server-side. `npm install` and all `npm run` startup scripts automatically create `.env` from the complete `.env.example` when it is absent. Prisma, Next.js, and the typed server configuration all read the same `DATABASE_URL`. Never commit `.env`. ## Quick start 1. Open the application and choose **Launch demo workspace** for a guided, curated tour. 2. Search for a paper, concept, or author and import a useful source. 3. Open a paper, select text in the PDF, and save a highlight or note. 4. Search across workspace material or use the Research Explorer to retrieve cited evidence. 5. Inspect relationships in the knowledge graph, synthesize a literature review, then export your result. Press Ctrl + K (or ⌘ + K) anywhere in the product to jump between research tools. ## Architecture ResearchOS is a modular monolith: one Next.js application with clear boundaries around the capabilities most likely to evolve—AI providers, data storage, identity, and background execution. ```mermaid flowchart TB UI["Next.js App Router\nServer & Client Components"] --> API["Typed route handlers\nvalidation · auth · response mapping"] API --> SVC["Application services\nuse cases · domain policies"] SVC --> PORTS["Ports & contracts"] PORTS --> DB[("Relational data")] PORTS --> OBJ[("Object storage")] PORTS --> ANALYSIS["Offline Analysis Engine\nBM25 · LexRank · local embeddings"] PORTS --> JOBS["Durable jobs & workers"] ``` - **UI stays presentational.** React components do not own business rules, database access, or secrets. - **Services own application behavior.** Routes validate, authorize, invoke a use case, and map a stable response. - **External dependencies live behind ports.** The database, object storage, queues, and optional local model adapters can evolve without leaking through the product. - **Derived analysis artifacts are traceable.** Algorithm version, input provenance, and schema version belong with durable results. Read more in [Architecture](docs/ARCHITECTURE.md), [Modules](docs/modules.md), and [API design](docs/api-design.md). ## Offline Analysis Engine ```mermaid sequenceDiagram participant R as Researcher participant W as Workspace participant I as Local index participant E as Analysis engine participant A as Artifact store R->>W: Ask a source-grounded question W->>I: Incrementally index workspace ev [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 245 recognized source files, 821 KB. - CSS (language) — detected in the code - Next.js (technology) — detected in the code - React (technology) — detected in the code - SQL (language) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - JavaScript (language) — claimed on Devpost, not found in the code - Node.js (technology) — claimed on Devpost, not found in the code - OpenAI (technology) — claimed on Devpost, not found in the code - Python (language) — claimed on Devpost, not found in the code - AI coding agent: Claude Code — evidence: config files committed to the repository - AI coding agent: Codex — evidence: config files committed to the repository ## Codebase structure (from repository index) ### Files (120 of 310) ``` .env.example .gitignore .prettierignore AGENTS.md app/api/.gitkeep app/api/annotations/.gitkeep app/api/annotations/[id]/route.ts app/api/export/.gitkeep app/api/export/[id]/download/route.ts app/api/export/[id]/route.ts app/api/export/bibtex/route.ts app/api/export/docx/route.ts app/api/export/html/route.ts app/api/export/route.ts app/api/graph/route.ts app/api/literature-review/.gitkeep app/api/literature-review/[id]/actions/route.ts app/api/literature-review/[id]/generate/route.ts app/api/literature-review/[id]/route.ts app/api/literature-review/[id]/sections/[sectionKey]/route.ts app/api/literature-review/route.ts app/api/notes/[id]/route.ts app/api/papers/[id]/annotations/.gitkeep app/api/papers/[id]/annotations/route.ts app/api/papers/[id]/chat/.gitkeep app/api/papers/[id]/chat/route.ts app/api/papers/[id]/conversations/.gitkeep app/api/papers/[id]/notes/route.ts app/api/papers/[id]/pdf/route.ts app/api/papers/[id]/reading-progress/route.ts app/api/papers/[id]/upload/route.ts app/api/papers/import/route.ts app/api/projects/[id]/export/route.ts app/api/projects/[id]/route.ts app/api/projects/route.ts app/api/recommendations/[paperId]/route.ts app/api/research-agent/.gitkeep app/api/research-agent/artifacts/route.ts app/api/research-agent/history/route.ts app/api/research-agent/run/route.ts app/api/research-agent/tasks/[id]/cancel/route.ts app/api/research-agent/tasks/[id]/pause/route.ts app/api/research-agent/tasks/[id]/resume/route.ts app/api/research-agent/tasks/[id]/route.ts app/api/research-agent/tasks/route.ts app/api/search/route.ts app/api/settings/ai/route.ts app/api/workspace/route.ts app/api/workspace/search/route.ts app/api/workspaces/route.ts app/demo/.gitkeep app/demo/page.tsx app/error.tsx app/export/.gitkeep app/export/page.tsx app/globals.css app/knowledge-graph/page.tsx app/layout.tsx app/library/[id]/page.tsx app/library/page.tsx app/literature-review/.gitkeep app/literature-review/page.tsx app/loading.tsx app/not-found.tsx app/onboarding/.gitkeep app/onboarding/page.tsx app/page.tsx app/projects/[id]/page.tsx app/projects/page.tsx app/research-agent/.gitkeep app/research-agent/page.tsx app/research-insights/page.tsx app/search/page.tsx app/settings/ai/page.tsx app/settings/page.tsx app/workspace/page.tsx CLAUDE.md components/.gitkeep components/ai-settings-panel.tsx components/ai/.gitkeep components/annotations/.gitkeep components/app-shell.tsx components/cross-paper-search.tsx components/demo/.gitkeep components/export/.gitkeep components/export/export-workspace.tsx components/graph/.gitkeep components/graph/knowledge-graph-view.tsx components/landing-page.tsx components/literature-review/.gitkeep components/literature-review/literature-review-workspace.tsx components/onboarding/.gitkeep components/pdf-viewer.tsx components/pdf/.gitkeep components/project-list.tsx components/project-workspace.tsx components/reading-workspace.tsx components/research-agent/.gitkeep components/research-agent/research-agent-dashboard.tsx components/research-assistant.tsx components/research-insights-dashboard.tsx components/research-sidebar.tsx components/search-workbench.tsx components/search/.gitkeep components/settings-panel.tsx components/ui/icons.tsx components/ui/primitives.tsx components/workspace-manager.tsx components/workspace-onboarding.tsx CONTRIBUTING.md demo-assets/papers/Computer_Vision/metadata.json demo-assets/papers/Graph_Neural_Networks/metadata.json demo-assets/papers/Machine_Learning/metadata.json demo-assets/papers/Quantum_Computing/metadata.json docs/api-design.md docs/API.md docs/ARCHITECTURE.md docs/DEMO.md docs/DEPLOYMENT.md docs/DEVELOPMENT.md [190 more files omitted for size] ``` ### Dependencies - package.json: @prisma/adapter-better-sqlite3@^7.8.0, @prisma/client@^7.8.0, @tailwindcss/postcss@^4, @types/better-sqlite3@^7.6.13, @types/node@^20, @types/react@^19, @types/react-dom@^19, better-sqlite3@^12.11.1, bibtex-parse-js@^0.0.24, cytoscape@^3.34.0, docx@^9.7.1, dotenv@^16.6.1, eslint@^9, eslint-config-next@16.2.10, file-saver@^2.0.5, framer-motion@^12.42.2, fuse.js@^7.5.0, graphology@^0.26.0, graphology-layout@^0.6.1, graphology-metrics@^2.4.0, graphology-shortest-path@^2.1.0, lunr@^2.3.9, markdown-it@^14.3.0, mime@^4.1.0, nanoid@^6.0.0, next@16.2.10, pdfjs-dist@5.4.296, pino@^10.3.1, playwright@^1.61.1, prettier@^3.9.5, prisma@^7.8.0, react@19.2.4, react-confetti@^6.4.0, react-dom@19.2.4, react-hotkeys-hook@^5.3.3, react-markdown@^10.1.0, react-pdf@^10.4.1, tailwindcss@^4, typescript@^5, uuid@^14.0.1, zod@^4.4.3 ### Recent commits (newest first) - updated - Add automated Playwright demo capture workflow and screenshots - Fix data integrity: separate user imports from demo enrichment - Validate remaining production limitations - Finalize ResearchOS v2.0 production implementation - Implement ResearchOS design system and production UI - feat(ui): implement ResearchOS design system and landing page - Add demo workspace onboarding and local research import pipeline - feat: add offline research workspace projects - feat: add interactive citation knowledge graph - feat(settings): separate offline, local, and cloud AI - feat: add AI Connect Plugin System v1.2.0 - feat: improve research themes extraction and remove stale AI code - release: v1.0.0 - Stable Offline ResearchOS Core - Initial fork from ResearchOS - Add offline mock AI provider for demo mode - Repair Prisma migration history and align PDF.js dependencies - Apply production audit improvements - Documentation complete - Prepare documentation structure ## Key source files (fetched from GitHub, selected and truncated for size) ### CLAUDE.md ```markdown @AGENTS.md ``` ### AGENTS.md ```markdown # This is NOT the Next.js you know This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices. ``` ### package.json ``` { "name": "researchos", "version": "0.1.0", "private": true, "scripts": { "bootstrap": "npm install && npm run setup", "env:ensure": "node scripts/bootstrap-env.mjs", "setup": "npm run env:ensure && npm run prisma:generate && npm run prisma:migrate", "postinstall": "npm run env:ensure", "demo:capture": "node scripts/capture-demo.ts", "dev": "npm run env:ensure && next dev", "build": "npm run env:ensure && npm run prisma:generate && next build", "start": "next start", "lint": "eslint", "format": "prettier --check .", "format:write": "prettier --write .", "prisma:generate": "npm run env:ensure && prisma generate", "prisma:migrate": "npm run env:ensure && prisma migrate dev" }, "dependencies": { "@prisma/adapter-better-sqlite3": "^7.8.0", "@prisma/client": "^7.8.0", "better-sqlite3": "^12.11.1", "bibtex-parse-js": "^0.0.24", "cytoscape": "^3.34.0", "docx": "^9.7.1", "file-saver": "^2.0.5", "framer-motion": "^12.42.2", "fuse.js": "^7.5.0", "graphology": "^0.26.0", "graphology-layout": "^0.6.1", "graphology-metrics": "^2.4.0", "graphology-shortest-path": "^2.1.0", "lunr": "^2.3.9", "markdown-it": "^14.3.0", "mime": "^4.1.0", "nanoid": "^6.0.0", "next": "16.2.10", "pdfjs-dist": "5.4.296", "pino": "^10.3.1", "prisma": "^7.8.0", "react": "19.2.4", "react-confetti": "^6.4.0", "react-dom": "19.2.4", "react-hotkeys-hook": "^5.3.3", "react-markdown": "^10.1.0", "react-pdf": "^10.4.1", "uuid": "^14.0.1", "zod": "^4.4.3" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/better-sqlite3": "^7.6.13", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "dotenv": "^16.6.1", "eslint": "^9", "eslint-config-next": "16.2.10", "playwright": "^1.61.1", "prettier": "^3.9.5", "tailwindcss": "^4", "typescript": "^5" }, "allowScripts": { "prisma@7.8.0": true, "@prisma/engines@7.8.0": true, "better-sqlite3@12.11.1": true } } ``` ### mappers/index.ts ```typescript export * from "@/mappers/research"; export * from "@/mappers/temporal"; ``` ### app/page.tsx ```typescript import { LandingPage } from "@/components/landing-page"; import { redirect } from "next/navigation"; import { LocalWorkspaceService } from "@/services/local-workspace-service"; export default async function Home() { if (!(await new LocalWorkspaceService().isOnboarded())) redirect("/onboarding"); return ; } ``` ### validators/index.ts ```typescript export * from "@/validators/api-error"; export * from "@/validators/ai"; export * from "@/validators/annotations"; export * from "@/validators/domain"; export * from "@/validators/export"; export * from "@/validators/literature-review"; export * from "@/validators/openalex"; export * from "@/validators/research-agent"; export * from "@/validators/pdf"; export * from "@/validators/request"; export * from "@/validators/response"; ``` ### services/index.ts ```typescript export * from "@/services/annotation-service"; export * from "@/services/collection-service"; export * from "@/services/crud-service"; export * from "@/services/export-service"; export * from "@/services/paper-service"; export * from "@/services/paper-reading-service"; export * from "@/services/local-workspace-service"; export * from "@/services/local-import-pipeline"; export * from "@/services/workspace-initializer"; export * from "@/services/demo-workspace-service"; export * from "@/services/knowledge-graph-service"; export * from "@/services/literature-review-service"; export * from "@/services/note-service"; export * from "@/services/project-service"; export * from "@/services/project-workspace-service"; export * from "@/services/reading-service"; export * from "@/services/recommendation-service"; export * from "@/services/research-agent-service"; export * from "@/services/research-insights-service"; export * from "@/services/research-workspace-service"; export * from "@/services/workspace-search-service"; export * from "@/services/search-service"; export * from "@/services/task-service"; export * from "@/services/workspace-service"; ``` ### app/layout.tsx ```typescript import type { Metadata } from "next"; import { Instrument_Sans, JetBrains_Mono } from "next/font/google"; import { AppShell } from "@/components/app-shell"; import "./globals.css"; const instrumentSans = Instrument_Sans({ variable: "--font-instrument-sans", subsets: ["latin"], }); const jetbrainsMono = JetBrains_Mono({ variable: "--font-jetbrains-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: { default: "ResearchOS", template: "%s | ResearchOS", }, description: "The local-first operating system for scientific research. Offline-first literature exploration and citation-network analysis.", }; const themeBootstrap = `try{var t=localStorage.getItem("researchos-theme");document.documentElement.setAttribute("data-theme",t==="light"?"light":"dark")}catch(e){}`; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return (