atlas-lab

Imported from xaverric/atlas-lab (AGENTS.md). Install upstream with npx skills add xaverric/atlas-lab. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Commands

# Development (individual services with hot reload via tsx watch)
npm run dev:core              # port 4000
npm run dev:dms               # port 4001
npm run dev:scheduler         # port 4002
npm run dev:notify            # port 4003
npm run dev:notes             # port 4004
npm run dev:gui               # Next.js dev server, port 3000

# Build & check (all workspaces)
npm run build
npm run typecheck
npm run lint

# Per-workspace
npm -w @atlas/server run dev
npm -w @atlas/dms run dev
npm -w @atlas/notes run dev
npm -w @atlas/gui run dev

# Docker startup modes (from root, wraps deployment/startup.sh)
npm run start:prod            # Production: all services in Docker behind Traefik
npm run start:dev             # Dev: all services in Docker with dev compose overrides
npm run start:local           # Local: infra + backends in Docker, GUI runs locally (hot reload)
# Add --reset suffix to wipe volumes: npm run start:dev:reset

# Init data loader (Keycloak users/roles, MinIO buckets)
npm run init

Architecture

Monorepo with npm workspaces. Node >= 22.

Shared packages (no build step, consumed as raw TS via tsconfig paths)

• packages/core (@atlas/core) — ApiError, TypeScript types (User, ApiResponse, PaginatedResponse), Zod validators (paginationSchema, objectIdSchema), constants (API_PREFIX = /api/v1)
• packages/server-common (@atlas/server-common) — Express middleware: createAuth (Keycloak JWT verification), validate (Zod), errorHandler, requireRole, connectDB (Mongoose), createLogger (pino)

Backend services

Frontend

• apps/atlas-gui (@atlas/gui) — Next.js 15 (App Router), port 3000
• lib/api.ts routes requests by path prefix: /api/v1/dms/* → DMS_URL, /api/v1/scheduler/* → SCHEDULER_URL, /api/v1/notes/* → NOTES_URL, etc.
• Auth via oidc-client-ts → Keycloak. AuthProvider context wraps app, lib/api.ts attaches JWT and handles silent refresh on 401.
• Protected routes under /(protected)/* layout with auth guard.

Infrastructure (Docker)

Production subdomains (ATLAS_DOMAIN=xaverric.cz): xaverric.cz (gui), api. (core), dms. (dms), scheduler. (scheduler), notify. (notify), notes. (notes), auth. (keycloak), s3. (minio API), storage. (minio console)

Backend layering

Route → Controller → Service → DAO → Model

• Routes mount auth/validation middleware (Zod schemas inline), delegate to controllers
• Controllers extract request data, call services, format { data: T } responses. No business logic.
• Services contain business logic, throw ApiError for error cases
• DAOs wrap Mongoose queries. No business logic.
• Models define Mongoose schemas with toJSON virtual transform (_id → id, delete __v)

All routes under API_PREFIX (/api/v1), except GET /health.

Auth

No custom auth — Keycloak handles everything.

1. Frontend oidc-client-ts redirects to Keycloak → callback exchanges code for tokens
2. lib/api.ts attaches access token, handles 401 with signinSilent()
3. Backend createAuth() verifies JWT against Keycloak JWKS endpoint
4. req.auth = decoded token (sub, email, name, realm_access.roles)
5. Inter-service auth (scheduler → notify): X-Internal-Key header
6. AI search (external → notes): X-Api-Key header, no JWT

Key service interactions

• scheduler → notify: Job success/failure hooks send HTTP POST with X-Internal-Key to queue a notification
• notes → ollama → qdrant: On note save, fire-and-forget generates embedding via Ollama, upserts to Qdrant. Search embeds query text → Qdrant vector similarity.
• dms → minio: Two S3 clients — internal (MINIO_ENDPOINT) for uploads, public (MINIO_PUBLIC_URL) for presigned download/preview URLs

Key conventions

• API responses: { data: T } for success, { error: string, details?: {} } for errors
• All inputs validated with Zod in validate() middleware
• Config from env vars with local defaults (config/index.ts in each service)
• @atlas/core and @atlas/server-common imported as source TS — no dist, no build
• Next.js uses output: 'standalone' for Docker builds
• Mongoose models use toJSON transform: _id → id, strip __v
• Qdrant point IDs: MongoDB ObjectId converted to UUID format (zero-padded)
• Notes store markdown in MongoDB, TipTap editor works with HTML, convert on load/save via turndown/showdown