Gravity

AIGravity/core Documentation

Overview of the AIGravity/core monorepo, including the web app, API service, AI service, local workflow, and CI structure.

AIGravity/core is a repo-backed monorepo, not a hosted SaaS. Clone the repository, run it locally, and adapt the services, CI, and infrastructure to your stack.

What AIGravity/core is

AIGravity/core is a monorepo that gives you a working full-stack baseline:

  • apps/web: Remix on port 3000
  • apps/api: NestJS running on Bun with GET /health on port 3001
  • apps/ai-service: FastAPI with GET /health on port 8001

The repo uses pnpm workspaces and Turborepo to orchestrate installs, builds, and local development across all services.

Start with this page to understand the architecture, then move to the Quickstart page to run the repo locally and the Features page to explore capabilities in depth.

Core services

Each service is pre-wired to work together in local development.

apps/web

Remix web app on http://localhost:3000. It connects to the API and can use the AI service through the repo's local workflows.

apps/api

NestJS API running on Bun at http://localhost:3001. It exposes GET /health and serves as the backend for the web app and AI service.

apps/ai-service

FastAPI service running on http://localhost:8001. It exposes GET /health and provides space for Python-based AI endpoints.

Monorepo tooling

Shared tooling with pnpm workspaces, Turborepo pipelines, linting/formatting, and common scripts for install, dev, and CI.

Versioning and CI/CD

Per-service VERSION files and GitHub Actions keep service releases isolated while building and publishing Docker images from main.

Integrations

Hooks and structure for wiring in external APIs, observability, and deployment targets. See the Integrations page for patterns and examples.

Architecture at a glance

Web app: apps/web

The web app is a Remix project served on http://localhost:3000.

  • Talks to the API at http://localhost:3001
  • Uses the shared monorepo toolchain for linting, build, and tests
  • Can reach the AI service through the backend or directly during local development

Run Gravity locally

Use these steps to clone the repository and bring all services up for local development.

Clone the repo

Clone AIGravity/core to your local machine.

git clone git@github.com:AIGravity/core.git
cd core

Bootstrap dependencies

Install dependencies and prepare the workspace with pnpm.

pnpm setup

Start all services

Run all core apps in dev mode using Turborepo.

pnpm dev

Successful startup shows log output for each service with ports:

  • Web: http://localhost:3000
  • API: http://localhost:3001
  • AI service: http://localhost:8001

Verify health checks

Confirm each service is responding.

curl http://localhost:3001/health
# {"status":"ok"}

AIGravity/core expects pnpm, Bun, and Python with uv-compatible tooling installed on your machine. See Quickstart for exact version recommendations and troubleshooting tips.

Versioning and CI/CD

AIGravity/core tracks versions per service and ships Docker images via GitHub Actions.

  • Each app has a VERSION file that defines its semantic version.
  • CI pipelines read these versions, build Docker images on merges to main, and publish to GitHub Container Registry (GHCR).
  • You can extend the workflows to push to your own registries or deployment targets.

This structure keeps service-level changes isolated while still benefiting from a shared monorepo.

Where to go next

Use these docs to move from exploration to customization.

Quickstart

Follow a focused path to run Gravity locally, inspect the services, and make your first code changes.

Features

Review the core capabilities of the web app, API, AI service, and monorepo tooling.

Integrations

Learn how to connect third-party APIs, add observability, and adapt Gravity to your deployment stack.

Changelog

Track updates to the starter kit, including service changes, tooling upgrades, and CI improvements.

Was this page helpful?

Last updated today

Built with Documentation.AI