SV-OS — Silicon Valley Learning OS

Google Maps for Computer Science Learning

---

📖 Overview

SV-OS is an interactive visual operating system that maps Computer Science concepts, technologies, projects, and careers into an explorable knowledge graph. It answers four critical questions:

• What should I learn next?
• Why should I learn it?
• What projects use it?
• Which careers require it?

Key Features

Feature	Description
🗺️ Knowledge Graph	Interactive graph visualization of 100+ connected CS concepts
🧭 Career Navigator	Personalized learning roadmaps for 9+ CS careers
📊 Progress Tracking	Track learning status across all concepts
🔍 Full-Text Search	Search across all nodes with ranked results
🌙 Dark Mode	Beautiful dark-first design system

---

🏗 Architecture

┌─────────────────────────────────────────────────────────┐
│                    Frontend (Vercel)                     │
│  Next.js 15 · TypeScript · Tailwind · React Query       │
│  Zustand · Framer Motion · React Flow · shadcn/ui       │
└────────────────────┬────────────────────────────────────┘
                     │ REST API (React Query)
┌────────────────────▼────────────────────────────────────┐
│                   Backend (Render)                       │
│  FastAPI · Python 3.12 · SQLAlchemy · Pydantic          │
│  Clean Architecture: Routes → Services → Repositories   │
└────────────────────┬────────────────────────────────────┘
                     │ Async Database
┌────────────────────▼────────────────────────────────────┐
│                Database (Supabase/Docker)                │
│  PostgreSQL 16 · Adjacency List Graph Model             │
│  Recursive CTEs · Full-Text Search · Row-Level Security │
└─────────────────────────────────────────────────────────┘

Monorepo Structure

sv-os/
├── apps/
│   ├── web/          # Next.js 15 frontend
│   └── api/          # FastAPI backend
├── packages/
│   ├── ui/           # Design system
│   ├── types/        # Shared TypeScript types
│   ├── config/       # Shared constants
│   ├── eslint-config/# ESLint configuration
│   └── tsconfig/     # TypeScript configuration
├── database/         # PostgreSQL schema + seed data
├── docs/             # Documentation
└── scripts/          # Utility scripts

---

🚀 Quick Start

Prerequisites

• Node.js 20+ · pnpm 9+ · Python 3.12+ · PostgreSQL 16+ (or Docker)

1. Install

git clone https://github.com/sv-os/sv-os.git
cd sv-os

# Frontend dependencies
pnpm install

# Backend (Python)
cd apps/api
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cd ../..

2. Database

# Using Docker (recommended)
docker compose up -d postgres

# Or use local PostgreSQL
createdb svos
psql -d svos -f database/schema.sql
bash scripts/seed.sh

3. Configure

cp apps/web/.env.local.example apps/web/.env.local
cp apps/api/.env.example apps/api/.env
# Edit both files with your credentials

4. Run

# Terminal 1: Backend API
cd apps/api && uvicorn app.main:app --reload

# Terminal 2: Frontend
pnpm dev:web

Open http://localhost:3000 for the app and http://localhost:8000/docs for API docs.

---

🛠 Development

Commands

Command	Description
pnpm dev	Start all apps
pnpm build	Build all apps
pnpm lint	Lint all apps
pnpm typecheck	TypeScript type checking
pnpm test	Run all tests
pnpm format	Format all files

Stack

Layer	Technology	Purpose
Framework	Next.js 15 (App Router)	React framework with SSR
Styling	Tailwind CSS v4	Utility-first CSS
UI	shadcn/ui + Radix	Accessible component primitives
Server State	TanStack React Query	API data caching & sync
Client State	Zustand	UI state management
Forms	React Hook Form + Zod	Typed form validation
Graph	React Flow	Knowledge graph visualization
Animation	Framer Motion	Micro-interactions & transitions
Backend	FastAPI	Async Python REST API
ORM	SQLAlchemy 2.0 (async)	Database access
Database	PostgreSQL 16	Primary data store
Auth	Supabase Auth	Authentication & RLS

---

📚 Documentation

Essential

Document	Description
Project Memory	Permanent AI onboarding file (archived)
Project Handoff	AI assistant handoff guide (archived)

Architecture & Design

Document	Description
Architecture	System architecture overview
Backend Blueprint	Backend stack & design
Frontend Blueprint	Frontend stack & design
Database Blueprint	Database schema design
API Blueprint	REST API specification

Knowledge Engine

Document	Description
Master Context	Full knowledge engine specification
Knowledge Graph Design	Graph philosophy & schema
Stage 5.2 Query Engine	Query & navigation API docs
Stage 5.3 Blueprint	Content layer design
Search Architecture	Search system design
Recommendation Engine	Recommendation system

Learning System

Document	Description
Learning Engine	Full learning engine spec
Learning Philosophy	Learning design philosophy
Cognitive Model	Cognitive science principles
Mastery Model	Mastery scoring & progression
Journey Design	Learner journey design
Project Engine	Project-based learning engine
Simulation Framework	Simulation system design

Infrastructure & Operations

Document	Description
Database Schema	Schema design & relationships
DB Migration Plan	Render to Neon migration
Deployment	Production deployment guide
Security	Security policies & auth
Testing Strategy	Testing approach & coverage
Performance Guide	Performance optimization

Reference

Document	Description
Engineering Standards	Coding standards & conventions
Implementation Guide	Implementation guidelines
Tech Decisions	Technology decisions & rationale
Product Evolution	Product roadmap & evolution
Cleanup Report	Documentation classification
Reorganization Report	Reorganization summary

Guides

Document	Description
Contributing	Contribution guidelines
Setup Guide	Local development setup
Monorepo Guide	Turborepo & pnpm usage
Runbook	Operational procedures

Archive

Historical documents preserved in docs/archive/ — not needed for daily development.

---

🗺 Knowledge Graph

Node Types

Type	Description	Color
Subject	Academic discipline	🟣 Purple
Concept	Core CS concept	🔵 Blue
Technology	Language, framework, tool	🟢 Green
Tool	Development tool	🟡 Amber
Career	Job role	🔴 Red
Project	Real-world project	🩷 Pink

Edge Types

prerequisite · depends_on · uses · enables · part_of · related_to · leads_to · requires

---

🤝 Contributing

See Contributing Guide.

📄 License

MIT — See LICENSE.