Deodat-Lawson/LaunchStack

LaunchStack – a TypeScript engine for AI‑native apps

What it is – LaunchStack is an open‑source, TypeScript‑first framework that bundles the plumbing most AI‑driven products need: document ingestion, OCR, vector‑store RAG, knowledge‑graph handling, LLM chat abstractions, background‑job orchestration, and related utilities (crypto, guardrails, credits, etc.). The core engine is deliberately framework‑agnostic; a Next.js reference app (apps/web) shows how a host can wire the engine’s ports to concrete services (Postgres + pgvector, S3, Inngest, etc.).

Key packages

Package	Status	Role
@launchstack/core	unpublished (will be released via Changesets)	Facade that re‑exports the layered engine (protocol, evidence, application, adapters). Provides DB, LLM, embeddings, OCR, RAG, graph, crypto, guardrails, ingestion, providers, storage, jobs, credits, errors.
@launchstack/features/*	internal	Ready‑to‑use verticals built on the core (e.g., document ingestion, legal‑template generation, marketing pipeline, voice, trend search).
packages/protocol, evidence, application, adapters	internal	Low‑level layers: contracts, pure domain logic, use‑case ports, concrete adapters.
apps/web	–	Next.js host that implements the ports (S3 storage, Inngest job dispatcher, PostgreSQL DB, etc.) and provides UI, auth, and the end‑user experience.
apps/worker	–	Durable workflow runner that processes the ingestion outbox and executes background jobs.
services/	–	Small auxiliary services (document conversion, transcription) written in Node or Python; not part of the pnpm workspace but used by the engine.

Architecture at a glance

apps/web (Next.js host) ──► createEngine(config) ──► @launchstack/core
        │                                 │
        │   registers ports: StoragePort (S3), JobDispatcherPort (Inngest),
        │   CreditsPort (DB), RagPort (hybrid pgvector + Neo4j), …
        ▼                                 ▼
@launchstack/features/* (vertical use‑cases)   engine internals (db, llm, ocr, …)

• The core knows nothing about Next.js, React, or any UI framework – it only exposes typed ports.
• Features import only those ports; they cannot reach into the host code.
• The host (the Next.js app) provides concrete implementations for the ports and supplies environment variables.
• All configuration is passed through a CoreConfig object; the engine never reads process.env directly (enforced by ESLint).

Running the project

• Prerequisites – Node ≥ 20, pnpm 10.15.1 (use corepack enable).
• Docker (recommended) – make up-prod (lite stack) or make up-ocr (adds Docling OCR). Use make down / make down‑clean to stop and optionally wipe volumes.
• Without Docker – Provide a PostgreSQL instance with the pgvector extension, then run the migration/seed commands and start the web and worker packages via pnpm --filter @launchstack/web dev and pnpm --filter @launchstack/worker dev.
• Chat configuration – By default the engine talks to Google Gemini’s OpenAI‑compatible endpoint. Override with CHAT_BASE_URL and CHAT_API_KEY to point at any OpenAI‑compatible service (OpenRouter, Ollama, vLLM, etc.). Embeddings, OCR, transcription, etc., have separate credential slots.

Current status

• The engine packages are not yet published to npm; the first release will be automated through the repository’s release.yml workflow.
• The reference app can be run locally or via Docker, giving a fully functional demo of ingestion → vector store → RAG → chat with guardrails.
• Roadmap items (mcp, workflow-generation, rules-extraction, connectors) exist only as scaffolding at the moment.

Who it’s for

• Teams building AI‑native SaaS products that need a solid, typed foundation for document processing, retrieval‑augmented generation, and LLM‑driven agents.
• Developers who prefer a clean separation between business logic (engine) and infrastructure (host) and want TypeScript‑first, port‑based design.
• Open‑source contributors interested in extending the vertical features or adding new adapters/providers.

How to contribute

• Follow the guidelines in CONTRIBUTING.md.
• Every change to a published engine package must be accompanied by a Changeset.
• Linting (including the custom import‑boundary rules) is a blocking CI step, so keep the core‑features‑host separation intact.

---

License – Apache 2.0.