---
### One-Command Setup
```bash
git clone https://github.com/CleanExpo/NodeJS-Starter-V1.git && cd NodeJS-Starter-V1 && pnpm run setup && pnpm dev
```
No API keys | No accounts | No configuration | Just works
### Upgrade an Existing Project
```bash
git remote add upstream https://github.com/CleanExpo/NodeJS-Starter-V1.git 2>/dev/null; git fetch upstream && git merge upstream/main --no-edit --allow-unrelated-histories && pnpm install && cd apps/backend && uv sync
```
Pulls the latest framework, agents, skills, and Anthropic integrations into your project
---
## Architecture
```mermaid
flowchart TB
subgraph Frontend["Frontend (Next.js 15)"]
direction LR
React["React 19"]
RSC["Server Components"]
TW["Tailwind v4"]
Shadcn["shadcn/ui"]
end
subgraph Backend["Backend (FastAPI)"]
direction LR
API["REST API"]
LG["LangGraph"]
Agents["AI Agents"]
Auth["JWT Auth"]
SSE["SSE Stream"]
end
subgraph Data["Data Layer"]
direction LR
PG[("PostgreSQL 15\n+ pgvector")]
Redis[("Redis 7\nCache")]
Supabase[("Supabase\nState (opt)")]
end
subgraph AI["AI Provider Layer"]
direction LR
Ollama["Ollama\n(Local/Free)"]
Claude["Claude API\n(Cloud/Paid)"]
end
Frontend -->|"REST + JWT"| Backend
Frontend <-->|"SSE tokens"| SSE
Backend -->|"SQLAlchemy"| Data
Backend -->|"Provider Selector"| AI
style Frontend fill:#0070f3,color:#fff
style Backend fill:#009688,color:#fff
style Data fill:#4169E1,color:#fff
style AI fill:#8b5cf6,color:#fff
```
View Data Flow Diagram
```mermaid
sequenceDiagram
participant U as User
participant F as Frontend
participant B as Backend
participant A as AI Agent
participant DB as PostgreSQL
participant SB as Supabase
U->>F: Request
F->>B: API Call (JWT)
B->>DB: Query Data
DB-->>B: Results
B->>A: Process with AI
alt Streaming Mode
A-->>F: SSE text_delta events
F-->>U: Real-time tokens
else Standard Mode
A-->>B: AI Response
B-->>F: JSON Response
F-->>U: Rendered UI
end
opt Supabase configured
B->>SB: Persist agent run
SB-->>B: Confirmed
end
```
---
## Getting Started
The quickest way to get up and running is with Docker Compose, which handles PostgreSQL, Redis, and all supporting services:
```bash
git clone https://github.com/CleanExpo/NodeJS-Starter-V1.git
cd NodeJS-Starter-V1
docker compose up -d # Start PostgreSQL + Redis
pnpm install && pnpm dev # Install deps and start dev servers
```
See the detailed Quick Start below for full prerequisites and verification steps.
### Start a NEW project from this template
This repo is a template: every new project inherits the full engineering standard
(strict types with no source-file exclusions, CI gates incl. secret scan + format +
Conventional Commits, agent harness, ADRs) on day one — the standard itself is recorded in
[docs/adr/0001-starter-pack-standard.md](docs/adr/0001-starter-pack-standard.md).
```bash
gh repo create / --template CleanExpo/NodeJS-Starter-V1 --private --clone
cd
bash scripts/bootstrap-new-project.sh # rename, env hygiene check, repo settings + branch protection
pnpm install && pnpm verify # must be green before the first feature
```
---
## Quick Start
Prerequisites
| Tool | Version | Download |
| ------- | ------- | -------------------------------- |
| Docker | Latest | [docker.com](https://docker.com) |
| Node.js | 20+ | [nodejs.org](https://nodejs.org) |
| Python | 3.12+ | [python.org](https://python.org) |
| pnpm | 9+ | `npm i -g pnpm` |
| Ollama | Latest | [ollama.com](https://ollama.com) |
Installation
```bash
# 1. Clone repository
git clone https://github.com/CleanExpo/NodeJS-Starter-V1.git
cd NodeJS-Starter-V1
# 2. Run automated setup
pnpm run setup # macOS/Linux
pnpm run setup:windows # Windows
# 3. Start development
pnpm dev
```
Verify Installation
```bash
pnpm run verify
```
| Service | URL | Status |
| ----------- | ---------------------- | ------- |
| Frontend | http://localhost:3000 | Running |
| Backend API | http://localhost:8000 | Running |
| PostgreSQL | localhost:5432 | Running |
| Redis | localhost:6379 | Running |
| Ollama | http://localhost:11434 | Running |
**Default Login:** `admin@local.dev` / `admin123`
---
## Features
### Design System
- **Scientific Luxury** tier UI
- OLED black backgrounds
- Spectral colour system
- Physics-based animations
- Design tokens configuration
---
## Project Structure
```
NodeJS-Starter-V1/
├── apps/
│ ├── web/ # Next.js frontend
│ │ ├── app/ # App Router pages
│ │ ├── components/ # React components
│ │ └── lib/api/ # API client
│ └── backend/ # FastAPI backend
│ └── src/
│ ├── agents/ # AI agents (LangGraph)
│ ├── api/ # REST endpoints + SSE
│ ├── auth/ # JWT authentication
│ ├── models/ # AI providers (Anthropic, Ollama)
│ └── state/ # State store (NullStore / Supabase)
├── .beads/ # AI agent memory (Beads)
├── .claude/ # Claude Code config & hooks
│ ├── hooks/scripts/ # Automation scripts
│ └── rules/ # Agent rules
├── .skills/ # Agent skills (70 installed)
│ └── custom/
│ ├── anthropic-features/ # Anthropic API capability reference
│ ├── anthropic-streaming/# SSE streaming patterns
│ └── anthropic-web-search/ # Web Search v2 integration
├── .claude/
│ ├── VAULT-INDEX.md # Wiki-link master index
│ ├── schemas/ # Frontmatter schema
│ └── hooks/scripts/ # Claude Code automation
├── docs/ # Documentation
│ ├── MULTI_AGENT_ARCHITECTURE.md
│ ├── DESIGN_SYSTEM.md
│ └── BEADS.md
├── scripts/ # Setup & utility scripts
└── .github/workflows/ # CI/CD pipelines
```
---
## Claude Code Integration
This starter includes full Claude Code (CLI) integration with hooks, agents, and skills.
Vault Index System
Obsidian-style wiki-linking for O(1) discovery of agents, skills, rules, and commands.
```bash
# Regenerate indexes after adding new files
pnpm vault:index
# Check for broken wiki-links
pnpm vault:validate
# Add frontmatter to existing .md files
pnpm vault:adopt
# Full initialisation (for downstream projects)
/vault-init
```
**Wiki-Link Syntax**:
- `[[skill-name]]` — lookup by ID
- `[[agent/frontend-specialist]]` — direct path
- `[[scientific-luxury#banned-elements]]` — section anchor
- `[[scientific-luxury|Design System]]` — custom text
Claude Code Commands
```bash
/vault-init # Initialise vault system
/verify # Run verification checks
/audit # Framework audit
/new-feature # Guided feature development
/minion # One-shot task execution
/skill-manager # Analyse skill gaps
```
---
## Development
Common Commands
```bash
# Start all services
pnpm dev
# Run tests
pnpm turbo run test
# Type check
pnpm turbo run type-check
# Lint
pnpm turbo run lint
# Docker management
pnpm run docker:up # Start services
pnpm run docker:down # Stop services
pnpm run docker:reset # Reset database
# Vault management
pnpm vault:index # Regenerate wiki-link indexes
pnpm vault:validate # Check for broken links
```
Backend Commands
```bash
cd apps/backend
# Run server
uv run uvicorn src.api.main:app --reload
# Run tests
uv run pytest --cov
# Type check
uv run mypy src/
# Lint
uv run ruff check src/
```
Frontend Commands
```bash
# Unit tests
pnpm test --filter=web
# E2E tests
pnpm test:e2e --filter=web
# Type check
pnpm type-check --filter=web
```
---
## AI Configuration
Local AI (Default - FREE)
```bash
# Default configuration (no changes needed)
AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1:8b
```
| Model | Size | Use Case |
| ---------------- | ----- | ------------- |
| llama3.1:8b | 4.7GB | General tasks |
| nomic-embed-text | 274MB | Embeddings |
Cloud AI — Claude API (Optional)
```bash
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-xxx
```
| Model | Input | Output | Capabilities |
| ----------------- | ----- | ------ | -------------------------------------- |
| Claude Opus 4.6 | $5/1M | $25/1M | Adaptive thinking, Fast Mode, 128K out |
| Claude Sonnet 4.6 | $3/1M | $15/1M | Adaptive thinking, web search, 64K out |
| Claude Haiku 4.5 | $1/1M | $5/1M | Fastest — high-throughput tasks |
> All models support: SSE streaming, token counting, prompt caching, structured outputs, code execution.
Anthropic Feature Flags (Optional)
Add to `apps/backend/.env.local` to enable advanced Anthropic API capabilities:
```bash
# Streaming (default: on)
STREAMING_ENABLED=true
# Adaptive Thinking — Opus 4.6 / Sonnet 4.6 only
THINKING_ENABLED=false
THINKING_BUDGET_TOKENS=10000
# Fast Mode — Opus 4.6 only, 2.5× faster output (research preview)
FAST_MODE_ENABLED=false
# Web Search Tool v2 — GA Feb 2026
WEB_SEARCH_ENABLED=false
WEB_SEARCH_MAX_USES=5
# Token safety guard
TOKEN_COUNT_WARNING_THRESHOLD=50000
# Agent Skills beta — Anthropic-managed Excel/Word/PDF processing
AGENT_SKILLS_ENABLED=false
# MCP Connector beta — connect remote MCP servers in the messages API
MCP_CONNECTOR_ENABLED=false
# VOICE_MODE: NOT available via Anthropic API.
# Voice is only in Claude.ai consumer app and Claude Code CLI.
```
> See `.skills/custom/anthropic-features/SKILL.md` for the full capability matrix.
Supabase State Backend (Optional)
Without Supabase, the app uses `NullStateStore` — all functionality works, state is ephemeral.
Add these vars to get persistent `conversations`, `tasks`, and `agent_runs` tables:
```bash
SUPABASE_URL=https://.supabase.co
SUPABASE_ANON_KEY=
# SUPABASE_SERVICE_ROLE_KEY= # Only needed for admin ops
# Share the Supabase JWT secret so Supabase-issued user JWTs pass auth:
JWT_SECRET_KEY=
```
Get these from your [Supabase dashboard → Settings → API](https://supabase.com/dashboard/project/_/settings/api).
The app automatically detects the credentials at startup and switches to `SupabaseStateStore`. If credentials are absent or the connection fails, it falls back to `NullStateStore` silently.
---
## Documentation
| Guide | Description |
| ------------------------------------------------------------- | ---------------------------- |
| [Quick Start](docs/guides/QUICK_START.md) | Get running in 10 minutes |
| [Local Setup](docs/LOCAL_SETUP.md) | Complete setup guide |
| [AI Providers](docs/AI_PROVIDERS.md) | Ollama vs Claude comparison |
| [Multi-Agent Architecture](docs/MULTI_AGENT_ARCHITECTURE.md) | Agent workflow specification |
| [Design System](docs/DESIGN_SYSTEM.md) | Scientific Luxury UI system |
| [Beads](docs/BEADS.md) | AI agent memory system |
| [Vault Index System](docs/VAULT_INDEX_SYSTEM.md) | Wiki-link O(1) lookup |
| [Testing Guide](docs/guides/TESTING_GUIDE.md) | Testing strategies |
| [CI/CD Guide](docs/guides/CI_CD_GUIDE.md) | Pipeline configuration |
| [Production Deployment](docs/guides/PRODUCTION-DEPLOYMENT.md) | Deployment options |
### Anthropic API Skills
| Skill | Description |
| ------------------------------------------------------------ | --------------------------------------------- |
| [anthropic-features](.skills/custom/anthropic-features/) | Full capability matrix — models, flags, betas |
| [anthropic-streaming](.skills/custom/anthropic-streaming/) | SSE streaming patterns for this project |
| [anthropic-web-search](.skills/custom/anthropic-web-search/) | Web Search v2 integration guide |
### Framework Documentation
- [Next.js](https://nextjs.org/docs) | [FastAPI](https://fastapi.tiangolo.com/) | [LangGraph](https://langchain-ai.github.io/langgraph/) | [Ollama](https://ollama.com/) | [shadcn/ui](https://ui.shadcn.com/) | [Anthropic API](https://platform.claude.com/docs/en/home)
---
## Troubleshooting
Ollama not running
```bash
# Install and start Ollama
curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.1:8b
ollama pull nomic-embed-text
ollama serve
```
Database connection errors
```bash
docker compose down
docker compose up -d
docker compose logs postgres
```
Port conflicts
```bash
# Check ports
lsof -i :3000 # Frontend
lsof -i :8000 # Backend
lsof -i :5432 # PostgreSQL
```
Dependency issues
```bash
rm -rf node_modules apps/*/node_modules
pnpm store prune
pnpm install
```
401 errors in backend tests
All backend tests use real HS256 JWTs — the `AuthMiddleware` is ASGI-layer and cannot be overridden by FastAPI `dependency_overrides`. Tests generate tokens via:
```python
from src.auth.jwt import create_access_token
from datetime import timedelta
AUTH_HEADERS = {
"Authorization": f"Bearer {create_access_token({'sub': 'test@example.com'}, timedelta(hours=24))}"
}
```
---
## Contributing
Contributions welcome! Please:
- Keep it self-contained (no required external services)
- Maintain offline-first capability
- Include tests for new features
- Update documentation
---
## Community
- [Licence (MIT)](./LICENSE)
- [Security Policy](./SECURITY.md)
- [Contributing Guide](./CONTRIBUTING.md)
- [Changelog](./CHANGELOG.md)
---
## Licence
MIT Licence — Use freely for any purpose.
---
**[Quick Start](#-quick-start)** | **[Documentation](#-documentation)** | **[Issues](https://github.com/CleanExpo/NodeJS-Starter-V1/issues)**
Built with care for developers who want to build AI apps without barriersLast Updated: 20/03/2026
