🚀 Create a Getting Started developer guide

[sbharatjoshi]

Summary

Spector needs a comprehensive "Getting Started" developer guide that walks new contributors from zero to a running local instance. The existing README covers features but doesn't provide a step-by-step build-from-source experience.

Why This Matters

The #1 barrier to OSS contribution is "I can't get it running locally." A great getting-started guide eliminates this friction entirely.

Scope

Location: docs/getting-started.md (new file, linked from README)

Sections to cover:

• Prerequisites

  • Java 25 (Temurin recommended) — installation instructions for macOS, Linux, Windows
  • Maven 3.9+
  • Ollama (for embedding model) — install + pull model
  • Docker (optional, for containerized run)
  • Git

• Clone & Build

  git clone https://github.com/spectrayan/spector.git
  cd spector
  mvn clean verify

  Expected output, common errors, troubleshooting

• Run Locally

  • Start Ollama: ollama serve
  • Pull embedding model: ollama pull nomic-embed-text
  • Start Spector: java -jar spector-node/target/spector-node-*.jar
  • Verify health: curl http://localhost:7070/health

• Your First Memory

  curl -X POST http://localhost:7070/api/v1/memories \
    -H 'Content-Type: application/json' \
    -d '{"content": "Spector uses a 4-tier cortex architecture"}'

• Architecture Overview

  • Brief explanation of the 22-module structure
  • Link to architecture docs
  • Dependency diagram (text-based is fine)

• Running Tests

  mvn test                    # Unit tests
  mvn verify                  # Unit + integration tests
  mvn test -pl spector-memory # Single module

• IDE Setup

  • IntelliJ IDEA recommended settings
  • Enable preview features (Java 25)
  • Import as Maven project

Acceptance Criteria

• A new contributor can go from git clone to running instance in < 15 minutes
• All commands are copy-pasteable and tested
• Covers macOS, Linux, and Windows
• Links back to README and CONTRIBUTING.md
• No broken links

Hints

• Test the guide yourself on a clean checkout!
• Common gotchas: wrong Java version, Ollama not running, port conflicts
• Screenshots are welcome but not required
• Look at how Milvus, Qdrant, and ChromaDB structure their getting-started guides for inspiration