Architecture Overview | Dataspheres AI Docs - Dataspheres AI

Architecture Overview Dataspheres AI is a full-stack TypeScript monorepo. The server and client share types but are deployed as a single Docker image, maki...

Architecture Overview Dataspheres AI is a full-stack TypeScript monorepo. The server and client share types but are deployed as a single Docker image, making it straightforward to self-host. Repository Layout dataspheres-ai/ ├── src/ │ ├── server/ # Express API (Node.js) │ │ ├── app.ts # App bootstrap — middleware, routes, startup │ │ ├── index.ts # Server entry point │ │ ├── config/ # Env-driven feature flags and vendor config │ │ ├── controllers/ # Request handlers (thin — delegate to services) │ │ ├── endpoints/ # Route definitions (v1 and v2 namespaces) │ │ ├── lib/ # Shared infra: Prisma singleton, cache, logger │ │ ├── middleware/ # Auth, rate-limiting, error handling │ │ ├── models/ # Prisma query helpers (the M in MVC) │ │ ├── routes/ # Express router wiring │ │ ├── services/ # Business logic layer │ │ ├── v1/ v2/ # Versioned API route trees │ │ └── websocket/ # WebSocket handlers (real-time features) │ └── client/ # React SPA (Vite) │ ├── components/ # UI components (Shadcn/UI + custom) │ ├── contexts/ # React context providers │ ├── hooks/ # Custom React hooks │ ├── lib/ # Client utilities and API clients │ └── pages/ # Route-level page components ├── prisma/ │ ├── schema.prisma # Data model (single source of truth) │ ├── migrations/ # SQL migration history │ └── seed.ts # First-run seed (admin account, default DS) ├── scripts/ # CLI utilities and CI checks ├── docker-compose.oss.yml # Zero-key quickstart compose file └── .env.example # Full env var reference Technology Stack Layer Technology Frontend React 19, Vite 7, TypeScript, Tailwind CSS, Shadcn/UI, React Three Fiber, Framer Motion Backend Node.js 20, Express, TypeScript Database PostgreSQL 15 with pgvector, Prisma 6 ORM Cache Postgres-based (namespace/key/TTL) — no Redis dependency AI (optional) OpenAI GPT-5, Google Vertex AI (Imagen 3 / Veo 3), ElevenLabs Conversational AI Testing Vitest (unit), Playwright (E2E) Deploy Docker on Render.com (or any Docker host) MVC Conventions The server follows a strict three-layer pattern. Every feature lives in exactly three places: Model ( src/server/models/ ) — Prisma query helpers. No business logic. Return typed results or throw. View ( src/client/components/ ) — React components. Consume API data via hooks. No direct DB access. Controller ( src/server/endpoints/ or v1/ / v2/ ) — Express route handlers. Validate input, call services, return JSON. Services ( src/server/services/ ) sit between controller and model and contain all business logic, including capacity charging, AI calls, and cross-model writes. API Versioning Two API namespaces co-exist: /api/v1/ — Page and content management. Accepts datasphere URI in the path. /api/v2/ — Task/planner and richer resource APIs. Accepts datasphere DB id in the path. Request Flow Browser → Vite Dev Server (5173) → [HMR in dev] ↕ API calls Browser → Express (3000) → Auth middleware (JWT verify) → Rate limiter → Controller (validate input) → Service (business logic) → Model (Prisma query) → PostgreSQL Feature Areas Area Key files Auth / Users src/server/services/auth.service.ts , src/server/middleware/auth.ts Dataspheres src/server/services/datasphere.service.ts Pages / Docs src/server/services/page.service.ts , src/server/services/oss-docs-seed.service.ts Tasks / Planner src/server/v2/ task routes, src/server/services/task.service.ts AI Completions src/server/services/completion.service.ts Graphs / Sequencer src/server/services/graph.service.ts Env / Feature flags src/server/config/env-report.ts In-product Docs src/server/services/oss-docs-seed.service.ts Zero-Key Boot All vendor integrations (OpenAI, ElevenLabs, Stripe, etc.) are wrapped in optional-client guards. When an API key is absent the feature reports "disabled — set KEY" in the boot log and returns a graceful degradation response to the frontend. The core platform (auth, pages, tasks, graphs, dataspheres) works fully without any paid keys.