ResearchOS — Developer Instructions (Summary)

1. Architecture Principles (Non-Negotiable)

 Build a browser-first platform (no desktop dependency).
 Follow microservices architecture (no monolith).
 Keep frontend (UI) and backend (logic) strictly separated.
 Use event-driven + async processing for agent workflows.
 All core operations must be API-driven.

2. Monorepo Setup
 Use Turborepo (or Nx).
 Maintain this structure:
o /apps → Frontend ([Link])
o /services → Backend microservices
o /agents → AI logic (LangGraph)
o /packages → Shared libraries
o /infrastructure → DevOps & deployment

3. Frontend (Browser App)

 Stack: [Link] + React + TypeScript + Tailwind
 Implement:
o Project dashboard
o Manuscript editor (Google Docs–like)
o Agent activity panel
o Review & revision UI
 Integrate WebSocket for real-time updates.
 Use Yjs (CRDT) for collaborative editing.

4. Backend Services
Each service must be independent and deployable:

 API Gateway → routing + auth

 Auth Service → JWT-based authentication
 Project Service → project lifecycle
 Manuscript Service → document storage + versioning
 Analysis Service → statistical engine (sandboxed)
  Collaboration Service → real-time sync (Yjs)
 Submission Service → journal submission automation
 Revision Service → reviewer workflow
 Verification Service → receipts + validation

5. AI Agent Layer (Core System)

 Use LangGraph for orchestration.
 Agents must be modular:
o LiteratureAgent
o ExperimentDesignAgent
o MethodologyAgent
o DataAnalysisAgent
o WritingAgent
o PeerReviewAgent
o PublicationAgent
o RevisionAgent
o PostPublicationAgent
 Agents must pass structured state, not raw text.

6. Data Layer
Use multiple databases for specialization:

 PostgreSQL → users, projects, manuscripts

 Neo4j → citation graph
 Pinecone/Milvus → embeddings search
 Redis → queues + caching
 S3 → file storage

7. Statistical Analysis Engine

 MUST run in Docker sandbox (no direct execution).
 Flow:
o Upload data → detect schema → check assumptions
o Select correct test automatically
o Generate code (Python/R/SPSS)
o Execute in container
o Return:
 Results
 APA text
 Figures
 Auto-detect violations and suggest alternatives.
8. Real-Time Collaboration
 Use:
o Yjs + WebSocket
 Features:
o Multi-user editing
o Cursor presence
o Inline comments
o Version snapshots

9. Verification & Trust Layer

Every operation must be traceable:

 Generate cryptographic receipts (input/output hash)

 Implement 3-Probe verification:
o Faithfulness
o Completeness
o Sufficiency
 Use HaluCheck for atomic fact validation
 No unverifiable output should be shown as final

10. Submission System

 Integrate via:
o APIs (if available)
o Headless browser automation (fallback)
 Support:
o Journal formatting
o Cover letter generation
o Submission tracking

11. Revision Workflow

 Parse reviewer comments using NLP
 Generate:
o Point-by-point responses
o Suggested edits
 Track:
o Revision rounds (R1, R2, R3)
o Changes via version control
12. DevOps & Deployment
 Use:
o Docker (all services)
o Kubernetes (scaling)
o GitHub Actions (CI/CD)
 Environments:
o Dev → Staging → Production
 Ensure:
o Logging
o Monitoring
o Auto-restart on failure

13. Security Requirements

 JWT authentication
 Role-Based Access Control (RBAC)
 AES-256 encryption (at rest)
 TLS 1.3 (in transit)
 Full audit logs for all actions

14. MVP Scope (Build First)

Do NOT build everything initially. Focus on:

1. Authentication
2. Project creation
3. Literature search + gap detection
4. Basic manuscript editor
5. Python-based analysis engine
6. APA result generator
7. Basic peer review simulation

15. Development Workflow

 Use feature-based branches
 Enforce code reviews (PR required)
 Maintain API contracts (OpenAPI/Swagger)
 Write unit tests for:
o Services
o Agents
o Analysis engine
16. Critical Constraints (Avoid Failure)
 Do NOT:
o Mix responsibilities across services
o Execute analysis outside sandbox
o Skip verification layer
o Hardcode AI outputs without validation
 Always design for:
o Scalability
o Reproducibility
o Auditability

17. Success Criteria (Technical)

 All outputs are verifiable
 System supports multi-user collaboration
 Analysis is reproducible
 Agent workflows are stateful and resumable
 End-to-end flow works:
Topic → Analysis → Writing → Review → Submission