Getting Started
Repository Tour
Every app and shared package in the Emofy monorepo, and what each one is for.
Emofy is a single Turborepo monorepo managed with pnpm workspaces. There
are two top-level folders that matter: apps/ (things you deploy) and
packages/ (shared code the apps depend on).
emofyplatform/
├── apps/ deployable applications (web, mobile, backend, docs)
├── packages/ shared libraries (auth, db, design system, SDKs, env)
├── docs/ written documentation, ADRs, runbooks, AI agent context
├── infra/ OpenTofu (IaC) for Railway + Vercel + Infisical sync
└── scripts/ repo automation (codegen, state, guards)Apps
Each app is independently deployable. Ports below are the local dev ports.
| App | Port | Stack | What it is |
|---|---|---|---|
backend | 3006 | NestJS 11 | The single API surface. All business logic, the database, queues, search, webhooks. Deployed to Railway. |
account | 3002 | Next.js 16 + Better Auth | The identity provider: sign-in, sign-up, 2FA, password reset, magic link, org switching, and credential management. |
consumer | 3007 | Next.js 16 | The main org-scoped web app — feed, messaging, tasks, the EMA launcher. Routed as /w/{orgId}/*. |
admin | 3003 | Next.js 16 | The super-admin console (Emofy staff): org and user management, feature flags, moderation. |
native | — | Expo 54 / React Native | The mobile app, mirroring consumer. Currently demo-stage, not production. |
docs | 3004 | Next.js / Fumadocs | This developer portal. |
marketing | 3008 | Next.js 16 | Public marketing site (emofy.com.tr). |
landing | 3000 | Next.js 16 | Legacy marketing site (emofy.net). |
template | 3005 | Next.js 16 | Shared scaffold/template for apps and EMAs. |
Every user authenticates through the account app, which issues a JWT. The other web apps consume that JWT and call the backend for data. See Authentication.
Shared packages
Packages are consumed via the @emofy/* workspace alias.
Foundation
| Package | Purpose |
|---|---|
@emofy/auth | Better Auth (v1.6.x) server + client config: sessions, RS256 JWT, 2FA, magic link, and the organization plugin that models multi-tenancy. |
@emofy/db | Drizzle ORM schemas. Two databases: emofyplatform_auth (identity, sessions, orgs) and emofyplatform_core (business data). Home of the OrgScopedRepository pattern. |
@emofy/types | The SSOT for RBAC: the 9 roles, the resource/action permission matrix, and branded ID types. |
@emofy/env | Folder-based, Zod-validated environment SSOT — one schema per deploy target (server, backend, consumer, native, docs…). |
@emofy/config | Shared Next.js / TypeScript presets, including EMA iframe CSP headers. |
Design system
| Package | Purpose |
|---|---|
@emofy/tokens | The token SSOT: raw + semantic color, spacing, radius, typography, motion. |
@emofy/rds | Ramarkable Design System primitives (~137 side-effect-free components). |
@emofy/ramarkable | Higher-level UI built on RDS: the EMA shell, permission-gated components, page templates. |
@emofy/icons | Shared SVG icon set. |
@emofy/storybook | Component documentation (Chromatic CI). |
Ecosystem & integration
| Package | Purpose |
|---|---|
@emofy/sdk | The in-app EMA SDK: a Penpal-based iframe bridge giving EMAs scoped RPC access to the host. |
@emofy/dev-sdk | The partner SDK: a typed TypeScript client for the public v1 API, with zero workspace coupling. |
@emofy/cli | The emofy binary — scaffold, validate (ema:doctor), and publish EMAs. |
@emofy/api-client | The shared low-level API client the frontends use to call the backend. |
@emofy/convex | The real-time backend (Convex): schema, hooks, provider for messaging/presence/live updates. |
@emofy/email | React Email + Resend templates (i18n: EN/TR). |
@emofy/e2e | The Playwright suite (also the source of the committed OpenAPI snapshot). |
Where the docs live in the repo
Beyond this portal, the repo carries its own written knowledge base:
docs/ai-context/AGENT_BOOTSTRAP.md— the canonical entry point.docs/ai-context/— architecture, best practices, workflow, and runbooks.docs/numbered files (e.g.001_SYSTEM_ARCHITECTURE_DEFINITION.md,004_MODULES.md) — the long-form system definition and module map.- Architecture Decision Records — summarized in the ADR index.