NEXUS

AI-Native Personal Knowledge x Action x Goal Management System

NEXUS is a unified system for capturing, organizing, and acting on your knowledge and work. Powered by AI agents that help you triage inbox items, link related knowledge, and stay focused on what matters.

Quick Start

Prerequisites

• Node.js 20+
• pnpm 9+
• Docker

Setup

# Clone the repository
git clone https://github.com/devstudio-tyler/nexus.git
cd nexus

# Run setup script
chmod +x scripts/setup.sh
./scripts/setup.sh

# Start development
pnpm dev

Access

• Web App: http://localhost:5173
• API: http://localhost:3000
• Neo4j Browser: http://localhost:7474 (neo4j / nexus_dev_password)

Project Structure

nexus/
├── apps/
│   ├── server/          # Express + TypeScript backend
│   └── web/             # React 19 + Vite frontend
├── packages/
│   ├── shared-types/    # TypeScript domain types
│   ├── shared-utils/    # Common utilities
│   └── api-client/      # Type-safe API client
├── specs/               # Specification files
│   ├── servers/         # Backend specs
│   └── pages/           # Frontend specs
└── docker/              # Docker configuration

Architecture

Hexagonal Architecture

The server follows hexagonal (ports & adapters) architecture:

• Domain: Core business logic (aggregates, events)
• Application: Use cases and orchestration
• Infrastructure: External adapters (Neo4j, OpenAI)
• Interfaces: HTTP routes and controllers

Spec-Driven Development

All features are defined in specification files before implementation:

# List all specs
pnpm spec:list

# Verify spec-code alignment
pnpm spec:check

Documentation

• CLAUDE.md - AI development instructions
• specs/README.md - Specification guidelines

Commands

pnpm dev          # Start all apps
pnpm dev:server   # Start backend only
pnpm dev:web      # Start frontend only
pnpm build        # Build all packages
pnpm test         # Run all tests
pnpm lint         # Lint all packages
pnpm spec:check   # Verify spec alignment

Docker

# Development
docker compose -f docker-compose.dev.yml up

# Production
docker compose -f docker-compose.prod.yml up

AI Agents

NEXUS includes four AI agents:

Agent	Purpose
Orchestrator	Routes user requests to appropriate agents
Knowledge Production	Creates and organizes notes
Knowledge Reinforcement	Strengthens knowledge connections
Secretary	Manages tasks and schedules

Data Model

NEXUS uses Neo4j for its graph database:

Work Breakdown Structure (WBS)

Area -> Initiative -> Project -> Work

Knowledge Base Structure (KBS)

Note <-> Note (linked)
InboxItem -> Note/Work (derived)

Environment Variables

Copy .env.example to .env and configure:

# Required
NEO4J_PASSWORD=your_password
OPENAI_API_KEY=sk-...
JWT_SECRET=your_secret

# Optional
NODE_ENV=development
PORT=3000

License

MIT