Monorepo Orientation

Kubuli is a pnpm workspace + Turborepo monorepo. All apps are in apps/ and shared code lives in packages/.

Repository layout

kubuli-monorepo/
├── apps/
│   ├── web/        # Nuxt 4 — marketing site + discovery platform
│   ├── api/        # HonoX — backend API
│   ├── admin/      # Laravel 13 — CMS and content console
│   ├── mobile/     # React Native — iOS and Android
│   └── docs/       # VitePress — this site
├── packages/
│   └── database/   # @kubuli/database — Prisma client + mirrored schema for TS apps
├── docs/           # Monorepo-wide architecture records
├── turbo.json      # Turborepo task pipeline
└── pnpm-workspace.yaml

Apps

apps/web — Discovery platform

Framework: Nuxt 4 (Vue 3) Purpose: Marketing site, real-time events feed, POI map, cultural explorer Port: 3000 Deploys to: Cloudflare Workers Key patterns: Composition API with <script setup>, Nuxt Content for static pages, Nuxt SEO

apps/api — Backend API

Framework: HonoX (Hono 4 + Vite) Purpose: RESTful data layer for web and mobile — events, places, culture, auth, tours Port: 3001 Language: TypeScript strict Key patterns: File-based routing under app/routes/api/, shared auth middleware, Prisma via @kubuli/database

apps/admin — CMS console

Framework: Laravel 13, Filament v5 Purpose: Content ingestion review, event/place/culture/media management, user roles Server: FrankenPHP (Octane) Key patterns: Filament resources for each content type, Spatie roles/permissions, n8n ingestion integration

apps/mobile — Mobile app

Framework: React Native Purpose: Native iOS and Android client Status: Early stage

apps/docs — Documentation site

Framework: VitePress Purpose: Audience-first docs for admins, developers, and integrators Port: 4173

Shared packages

@kubuli/database

Prisma schema mirror plus the shared Prisma client singleton for the TypeScript apps. All apps that need Prisma access import from here.

import { prisma } from "@kubuli/database";
import type { Event, Place } from "@kubuli/database";

Commands:

pnpm --filter=@kubuli/database db:generate   # Regenerate Prisma client after db pull
pnpm --filter=@kubuli/database db:studio     # Open Prisma Studio

Laravel owns the shared schema migrations in apps/admin. After those migrations run, sync Prisma from the live database with prisma db pull, then regenerate the client.

Cross-app data flow

Ingestion agents (n8n)
  → POST /admin/api/ingest/{type}
      Admin CMS (Laravel + Filament)
          → Curator reviews, approves, promotes
              PostgreSQL (shared database)
                  ← API reads canonical records
                      Web / Mobile clients

Turborepo task pipeline

Tasks are defined in turbo.json. Key tasks:

Task	Runs in	Cache
build	All apps/packages	Yes — dist/**
dev	All apps/packages	No — persistent
test	All apps/packages	Yes
lint	All apps/packages	Yes
type-check	TS apps/packages	Yes

Ownership and context files

Each app ships an AGENTS.md with AI agent context and a README.md with developer setup. Architecture decisions that span multiple apps live in docs/architecture/. Per-app decisions live in apps/{app}/docs/.