Project Structure

Manacore uses a pnpm workspace monorepo with Turborepo for build orchestration.

Overview

Directoryapps/ Main product applications
- Directorychat/
  - Directoryapps/
    Directorybackend/ NestJS API
    …
    Directorymobile/ Expo React Native
    …
    Directoryweb/ SvelteKit app
    …
    Directorylanding/ Astro marketing page
    …
  - Directorypackages/ Chat-specific packages
    …
- Directorypicture/
  - …
- Directoryzitare/
  - …
- Directorycontacts/
  - …
- Directorycalendar/
  - …
- …
Directoryservices/ Standalone microservices
- Directorymana-core-auth/ Central authentication
  - …
- Directorymana-search/ Search & content extraction
  - …
- Directorymana-tts/ Text-to-speech
  - …
- Directorymana-stt/ Speech-to-text
  - …
Directorypackages/ Shared packages
- Directoryshared-auth/ Client auth utilities
  - …
- Directoryshared-nestjs-auth/ NestJS auth guards
  - …
- Directoryshared-storage/ S3 storage utilities
  - …
- Directoryshared-ui/ React Native components
  - …
- Directoryshared-types/ TypeScript types
  - …
- Directoryshared-utils/ Utility functions
  - …
- …
Directorydocker/ Docker configurations
- …
Directorydocs/ Documentation source files
- …
Directory.claude/ Claude Code guidelines
- …

Apps Structure

Each application in apps/ follows a consistent structure:

apps/{project}/
├── apps/
│   ├── backend/     # NestJS API (optional)
│   ├── mobile/      # Expo app (optional)
│   ├── web/         # SvelteKit app
│   └── landing/     # Astro landing page
├── packages/        # Project-specific packages
├── package.json     # Project root (for turbo)
└── CLAUDE.md        # Project documentation

App Types

Type	Framework	Purpose
`backend`	NestJS 10-11	REST API, business logic, database access
`web`	SvelteKit 2 + Svelte 5	Main web application
`mobile`	Expo SDK 52+	iOS and Android app
`landing`	Astro 5	Marketing/landing page

Services

The services/ directory contains standalone microservices:

Service	Port	Purpose
`mana-core-auth`	3001	Central authentication (EdDSA JWT)
`mana-search`	3021	Web search & content extraction
`mana-tts`	3031	Text-to-speech generation
`mana-stt`	3032	Speech-to-text transcription

Shared Packages

Packages in packages/ are shared across all applications:

Authentication

@manacore/shared-auth - Client-side auth utilities
@manacore/shared-nestjs-auth - NestJS JWT guards
@mana-core/nestjs-integration - Full NestJS auth + credits module

UI & Styling

@manacore/shared-ui - React Native components
@manacore/shared-landing-ui - Astro landing page components
@manacore/shared-theme - Theme configuration
@manacore/shared-tailwind - Tailwind presets

Data & Utilities

@manacore/shared-types - Common TypeScript types
@manacore/shared-utils - Utility functions
@manacore/shared-storage - S3 storage utilities
@manacore/shared-i18n - Internationalization

Workspace Configuration

pnpm-workspace.yaml

packages:
  - 'apps/*'
  - 'apps/*/apps/*'
  - 'apps/*/packages/*'
  - 'services/*'
  - 'packages/*'

turbo.json

Turborepo handles task orchestration with:

Parallel execution for independent tasks
Dependency ordering for build tasks
Caching for faster rebuilds

Naming Conventions

Type	Pattern	Example
App package	`@{project}/{app}`	`@chat/backend`
Shared package	`@manacore/shared-{name}`	`@manacore/shared-auth`
Service	`@mana-{name}/service`	`@mana-search/service`

Adding a New Project

Create the directory structure:

mkdir -p apps/myproject/apps/{backend,web,landing}

Add a CLAUDE.md with project documentation
Create package.json files for each app
Add commands to root package.json
Configure in turbo.json if needed

See the existing projects as templates.