DevAtlas Platform

A production-grade developer atlas monorepo — technical content platform with AI-powered discovery, NestJS API, and Next.js frontend.

---

Table of Contents

• Overview
• Tech Stack
• Architecture
• Features
• Quick Start
• Docker Compose
• Testing
• Agent Automation
• API Documentation
• Scripts & Operations
• Contributing
• License

---

Overview

DevAtlas is a developer-focused content platform built as a pnpm + Turborepo monorepo. It combines a rich technical content library (guides, tools, categories) with AI-powered search and content discovery — using DeepSeek (local or hosted) to generate summaries, enhance search rankings, and surface related content.

The platform provides curated developer tools and guides across 20+ categories, with a NestJS backend handling content management, search indexing, user auth, and analytics, while the Next.js frontend delivers a fast, SEO-optimized browsing experience.

---

Tech Stack

Layer	Technology	Version
Monorepo	pnpm + Turborepo	pnpm 10.33, Turbo 2.10
Language	TypeScript (strict)	5.9
Linting	ESLint	10
Testing	Vitest	4
Web	Next.js + React	16 / 19
Styling	Tailwind CSS	4
API	NestJS	11
ORM	Drizzle ORM	0.45
Database	PostgreSQL	15
Validation	class-validator + class-transformer	0.15 / 0.5
API Docs	Swagger / OpenAPI	—
AI	DeepSeek (local + hosted)	—
Container	Docker Compose	—
CI/CD	GitLab CI + custom scripts	—

---

Architecture

devatlas/
├── apps/
│   ├── api/                    # NestJS 11 REST API
│   │   └── src/
│   │       ├── modules/        # Domain modules (15 modules)
│   │       │   ├── ai/         # AI summaries & embeddings (DeepSeek)
│   │       │   ├── auth/       # Auth (JWT, Passport, OAuth)
│   │       │   ├── billing/    # Billing & subscriptions
│   │       │   ├── categories/ # Content categories
│   │       │   ├── content-relations/ # Related content engine
│   │       │   ├── dashboard/  # Admin dashboard
│   │       │   ├── database/   # DB management & migrations
│   │       │   ├── engine/     # Content processing engine
│   │       │   ├── guides/     # Technical guides CRUD
│   │       │   ├── health/     # Health check endpoints
│   │       │   ├── orgs/       # Organizations
│   │       │   ├── search/     # Full-text search & indexing
│   │       │   ├── tags/       # Content tags
│   │       │   └── tools/      # Developer tools CRUD
│   │       ├── common/         # Shared interceptors, filters, guards
│   │       ├── config/         # Environment & app configuration
│   │       └── db/             # Drizzle schema & migrations
│   └── web/                    # Next.js 16 App Router frontend
│       ├── app/                # Route segments (27 routes)
│       │   ├── guides/         # /guides, /guides/[slug]
│       │   ├── tools/          # /tools, /tools/[slug]
│       │   ├── categories/     # /categories
│       │   ├── tags/           # /tags
│       │   ├── search/         # /search
│       │   ├── admin/          # Admin dashboard pages
│       │   ├── auth/           # Authentication pages
│       │   └── orgs/           # Organization pages
│       └── features/           # Domain feature modules
│           ├── ai/             # AI summary UI components
│           ├── auth/           # Auth hooks & API
│           ├── categories/     # Category components & API
│           ├── home/           # Home page sections
│           ├── navigation/     # Header, footer, navigation
│           ├── orgs/           # Organization components
│           ├── search/         # Search UI & hooks
│           └── tools/          # Tool components & API
├── packages/
│   ├── api-client/             # Generated OpenAPI client
│   ├── config/                 # Shared configuration
│   ├── content/                # Content types & utilities
│   ├── engine/                 # Content processing engine
│   ├── types/                  # Shared TypeScript definitions
│   ├── ui/                     # Shared React components
│   └── utils/                  # Shared utilities
├── scripts/                    # 40+ automation & ops scripts
│   ├── deploy/                 # Deployment scripts (staging, production)
│   ├── agent-*.mjs             # AI agent automation scripts
│   ├── gapcode-*.mjs           # Gap analysis & code quality
│   ├── backup-database.sh      # PostgreSQL backup
│   ├── restore-database.sh     # PostgreSQL restore
│   ├── doctor.mjs              # System diagnostics
│   └── health.mjs              # Health verification
├── infra/
│   ├── docker/                 # Docker Compose + Dockerfiles
│   │   ├── docker-compose.yml  # PostgreSQL + API + Web
│   │   ├── Dockerfile.api
│   │   ├── Dockerfile.web
│   │   └── postgres/           # Init scripts
│   └── monitoring/             # Prometheus + Grafana
│       ├── prometheus.yml
│       ├── grafana-dashboard.json
│       └── alert_rules.yml
├── docs/                       # Documentation
├── .githooks/                  # Git hooks (pre-commit, pre-push)
├── .env.example                # Root environment template
├── pnpm-workspace.yaml         # Workspace configuration
├── eslint.config.mjs           # ESLint flat config
├── commitlint.config.js        # Conventional commit linting
├── package.json                # Root package with all scripts
└── tsconfig.json               # Root TypeScript config

API Routes

Prefix	Description
/api/v1/health	Liveness / readiness probes
/api/v1/guides	Technical guides CRUD
/api/v1/tools	Developer tools CRUD
/api/v1/categories	Content categories
/api/v1/tags	Content tags
/api/v1/search	Full-text search & discovery
/api/v1/content-relations	Related content suggestions
/api/v1/ai	AI summaries & embeddings
/api/v1/auth	Authentication (JWT, OAuth)
/api/v1/orgs	Organization management
/api/v1/dashboard	Admin dashboard data
/api/v1/billing	Billing & subscriptions

Web Routes

Route	Description
/	Home page with platform overview
/guides	Browse all technical guides
/guides/[slug]	Individual guide with AI summary
/tools	Browse all developer tools
/tools/[slug]	Individual tool with related content
/categories	Browse content categories
/tags	Browse content tags
/search	Full-text search
/admin	Admin dashboard
/auth / /login / /register	Authentication

---

Features

• Curated Content Library — Guides and developer tools organized by categories and tags
• AI-Powered Discovery — DeepSeek-generated summaries, embeddings, and related content suggestions
• Full-Text Search — PostgreSQL-powered search with relevance ranking and filtering
• Content Relations Engine — Automatic related-content suggestions across guides and tools
• Responsive Frontend — Next.js 16 with App Router, Tailwind CSS, and dark mode
• RESTful API — NestJS with Drizzle ORM, Swagger docs, and class-validator
• Authentication — JWT + OAuth (GitHub, Google) with Passport.js
• Organizations — Multi-tenant org support with team management
• Admin Dashboard — Content management, analytics, and billing
• Docker Compose — One-command local production environment
• CI/CD Pipeline — Automated linting, type-checking, testing, and deployment
• Backup & Restore — Automated PostgreSQL backup/restore scripts
• Monitoring — Prometheus metrics + Grafana dashboards
• Offline-Friendly — Local DeepSeek AI support for bandwidth-constrained environments

---

Quick Start

Prerequisites

• Node.js 20.11+ (see .nvmrc)
• pnpm 10+
• PostgreSQL 15+

Install

pnpm install
cp .env.example .env

Set up the database

cd apps/api
cp .env.example .env      # Edit DATABASE_URL as needed
pnpm db:migrate            # Run Drizzle migrations
pnpm db:seed               # (Optional) Seed with sample data
cd ../..

Run locally

pnpm dev

Or per application:

pnpm dev:api     # NestJS → http://localhost:3001
pnpm dev:web     # Next.js → http://localhost:3000

---

Docker Compose

Start the full stack (PostgreSQL + API + Web) with a single command:

docker compose -f infra/docker/docker-compose.yml up --build

Service	Port	Health Check
PostgreSQL	5432	pg_isready
API	3001	/api/v1/health/live
Web	3000	Next.js built-in

Resource limits: 512 MB RAM / 1 CPU per service.

---

Testing

pnpm test                     # Run all tests (Turborepo)
pnpm test:api                 # API tests only (Vitest)
pnpm test:web                 # Web tests only (Vitest)

pnpm typecheck                # TypeScript type checking
pnpm lint                     # ESLint across all packages
pnpm verify:api               # db:check + lint + typecheck + test
pnpm verify:web               # lint + typecheck + test
pnpm doctor                   # System diagnostics
pnpm health                   # Full repo health check

---

Agent Automation

DevAtlas includes a sophisticated agent automation system for code review, quality assurance, and operations:

pnpm agent:autopilot          # Fully autonomous development loop
pnpm agent:smart              # Adaptive daily quality loop
pnpm agent:auto               # Connected mode with DeepSeek review
pnpm agent:auto:offline       # Safe mode — no internet required
pnpm agent:preflight          # Combined readiness pass
pnpm agent:deepseek           # Code review via hosted DeepSeek
pnpm agent:deepseek:local     # Code review via local Ollama model
pnpm agent:devflow            # Interactive development flow
pnpm agent:ops                # Operations & monitoring loop
pnpm agent:vps                # VPS audit & status
pnpm agent:verify             # Agent-oriented verification
pnpm agent:context            # Context gathering for agents
pnpm agent:tools              # Tools architecture audit

---

API Documentation

When running, the Swagger UI is available at:

http://localhost:3001/docs

The API uses URI versioning with /api/v1/ as the default prefix. Global response normalization is handled by TransformInterceptor and HttpExceptionFilter.

API Client

Generate a typed OpenAPI client:

pnpm generate:api-client

The generated client lives in packages/api-client/ and is consumed by the web app.

---

Scripts & Operations

Command	Purpose
pnpm doctor	System diagnostics and dependency check
pnpm health	Full repo health verification
pnpm backup:database	PostgreSQL backup to file
pnpm restore:database	Restore PostgreSQL from backup
pnpm search:smoke	Search indexing smoke test
pnpm staging:readiness	Staging environment readiness check
pnpm deploy	Full deployment pipeline
pnpm deploy:staging	Staging release
pnpm deploy:production	Production deployment
pnpm gapcode:index	Gap analysis code index

---

Contributing

See CONTRIBUTING.md for detailed guides on:

• Setup and installation
• Branch naming conventions
• Conventional commit messages
• Code style and naming conventions
• Database workflow with Drizzle
• Testing requirements
• Pull request checklist

All contributions must pass:

pnpm typecheck
pnpm lint
pnpm test
pnpm build

---

License

MIT — Copyright (c) 2026 DevAtlas