Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DrDigett/Babel/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide you will have a fully running local instance of BaBel+ with its seeded philosophy and film graph, the React SPA hot-reloading in the browser, and a working API ready to accept your first node — all from a single npm run dev command.
Prerequisites
  • Node.js ≥ 18 — BaBel+ uses native ESM and crypto.randomUUID(); older versions are not supported.
  • PostgreSQL — a local installation or a free cloud instance (e.g. Render, Supabase, or Neon) works equally well. You need a connection string of the form postgresql://user:password@host:5432/dbname.
  • Groq API key — free tier is sufficient. Obtain one at https://console.groq.com.
1

Clone the repository

Clone the BaBel+ monorepo from GitHub and move into the project root:
git clone https://github.com/DrDigett/Babel.git && cd Babel
2

Install dependencies

BaBel+ uses npm workspaces. A single install from the monorepo root resolves all packages — @babel-plus/server, @babel-plus/client, and @babel-plus/shared — at once:
npm install
3

Configure environment

The server reads its configuration from packages/server/.env. Copy the example file and fill in your values:
cp packages/server/.env.example packages/server/.env
Then open packages/server/.env and set at minimum DATABASE_URL and GROQ_API_KEY:
packages/server/.env
DATABASE_URL=postgresql://user:password@localhost:5432/babel
GROQ_API_KEY=gsk_...
PORT=3000
CORS_ORIGIN=*
JWT_SECRET=change-me-in-production
NODE_ENV=development
VariableRequiredDescription
DATABASE_URL✅PostgreSQL connection string
GROQ_API_KEY✅Groq API key for AI classification
PORTOptionalHTTP port for the Hono server (default 3000)
CORS_ORIGINOptionalAllowed CORS origin (default *)
JWT_SECRETOptionalSecret for auth tokens (defaults to a dev-only fallback; always set in production)
NODE_ENVOptionalSet to production when serving the built SPA
VITE_API_URL — if you need the React client to talk to an API server on a different host, create a .env file at the monorepo root (not inside packages/server/) and set VITE_API_URL=http://localhost:3000. In the default local dev setup this is not needed because Vite’s dev server already proxies all /api requests to http://localhost:3000 automatically.
4

Run the development server

Start both the Hono API server and the Vite client dev server concurrently with a single command from the monorepo root:
npm run dev
This runs tsx watch src/index.ts for the server and vite for the client in parallel (via concurrently). On first boot, the server automatically:
  1. Runs all pending SQL migrations to create the nodes, relations, lists, and list_nodes tables.
  2. Detects an empty database and runs the seed script (≈ 20 philosophy and film nodes with pre-built relations).
Once both processes are ready you will see output similar to:
[server] BaBel+ API running on http://0.0.0.0:3000
[client]   ➜  Local:   http://localhost:5173/
Open http://localhost:5173 in your browser to explore the graph.
5

Create your first node

With the server running, add a book node via the REST API:
curl -X POST http://localhost:3000/api/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "The Structure of Scientific Revolutions",
    "type": "libro",
    "author": "Thomas S. Kuhn",
    "year": 1962,
    "status": "pendiente",
    "priority": "alta",
    "tags": ["ciencia", "filosofia", "epistemologia"]
  }'
A successful request returns 201 Created with the persisted node object, including its generated id, createdAt, and updatedAt timestamps. The node will immediately appear in both the list view and the force-directed graph canvas in your browser.Field reference:
FieldTypeValues
titlestringRequired. Display name of the node.
typestringFree-form string. Common values: libro, pelicula, articulo, video, curso, videojuego, autor, concepto.
statusstringpendiente, en_progreso, terminado
prioritystringbaja, media, alta
authorstringOptional. Author or creator name.
yearnumberOptional. Publication or release year.
tagsstring[]Optional. Free-form classification labels.
linkstringOptional. External URL.
ratingnumberOptional. Personal rating (1–5).
Seed data included. When the server starts against an empty database it automatically inserts ~20 interconnected philosophy and film nodes — including works by Marx, Hegel, Bakunin, Fanon, and Debord, plus the film La Batalla de Argel — along with 19 pre-built relations. This gives you a live graph to explore immediately without entering data by hand. Run npm run db:seed at any time to re-seed manually.

​
What’s next

Nodes & Relations

Deep-dive into node types, relation semantics, and how the graph data model works.

AI Smart Add

Let Groq classify and connect a new node automatically from a single text prompt.

Build docs developers (and LLMs) love

Get started for freeTalk to us