project

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Project Structure (Monorepo)

The repo is a Turborepo monorepo split into two workspaces: `packages/` holds the shared, versionless building blocks, and `apps/` holds the deployable apps. Everything in `packages/` is one of three families — `core-*`, `platform-*`, or `feature-*` — and each `apps/` entry is a deployable target (`mobile`, `web`, `backend`, `e2e`). Each family has a fixed job and a fixed place in the dependency graph. Get the family and the direction right and the graph stays acyclic, features stay swappable, and a change to one feature can never ripple sideways into another.

Two rules hold the whole thing together: **dependencies only ever point downward** (`apps/* → feature-* → platform-* → core-*`), and **every package is a black box** reached only through its published entry point. The rest of this file is those two rules plus the naming and internal-structure conventions that keep them enforceable.

```
packages/
  core-*/          platform-agnostic foundation — reusable, no platform knowledge
                   (core-ui, core-utils, core-hooks, core-trpc, core-store,
                   core-config, core-i18n, core-types …)
  platform-*/      platform-specific building blocks — native modules, React Native
                   UI, device APIs (platform-ui, platform-navigation, platform-storage …)
  feature-*/       product features — one capability each (feature-quidditch,
                   feature-sorting-hat, feature-auth …), sub-features via feature-x-y
apps/
  mobile/          Expo / React Native app
  web/             Next.js app
  backend/         API / server
  e2e/             end-to-end tests (Detox / Playwright)
```

## Quick Reference

| Family | Location | Role | May depend on | Never depends on |
| --- | --- | --- | --- | --- |
| `core-*` | `packages/core-*` | Platform-agnostic foundation | other `core-*` only | `platform-*`, `feature-*`, apps |
| `platform-*` | `packages/platform-*` | Platform-specific foundation | `core-*`, sibling `platform-*` | `feature-*`, apps |
| `feature-*` | `packages/feature-*` | One self-contained product capability | `core-*`, `platform-*`, own sub-features | other features' internals, apps |
| app | `apps/{mobile,web,backend,e2e}` | Deployable app; wires everything together | `feature-*`, `platform-*`, `core-*` | — (nothing depends on an app) |

## The Families

### `core-*` — the platform-agnostic foundation

`core-*` packages are the reusable, **platform-agnostic** foundation the rest of the repo is built on: `core-ui`, `core-utils`, `core-hooks`, `core-trpc` (the API layer), `core-store`, `core-config`, `core-i18n`, `core-types`, `core-theme`, `core-services`, and so on. They contain no product logic, no knowledge of any single feature, and no platform-specific code — a `core-ui` primitive doesn't know the Sorting Hat exists, and it doesn't reach for a native module.

Core sits at the bottom of the graph. A core package **may build on other core packages** (`core-ui` can use `core-utils`), but it must never import a `platform-*`, `feature-*`, or app. If a core package finds itself needing a native module, that code belongs in `platform-*`; if it needs something from a feature, the dependency is pointing the wrong way.

### `platform-*` — the platform-specific foundation

`platform-*` packages hold the code that **can't be platform-agnostic**: native modules, React Native / native UI, device APIs, and other target-specific building blocks — `platform-ui`, `platform-navigation`, `platform-storage`, and so on. They keep the platform-specific surface in one layer so features stay mostly declarative.

Platform sits just above core: a `platform-*` package **may depend on `core-*`** (and on sibling `platform-*` packages), but never on a `feature-*` or an app. Think of it as core's platform-bound half — same "foundation" role, but tied to a runtime.

### `feature-*` — one product capability

A `feature-*` package is a single, self-contained product capability — `feature-auth`, `feature-quidditch`, `feature-sorting-hat` — composed out of `core-*` and `platform-*` pieces. It owns its screens, its hooks, its local state, and its slice of the API surface, and it exposes a small public API for apps to mount.

Large features decompose into **sub-features** through naming, not nesting: `feature-project`, `feature-project-create`, `feature-project-create-detail`. A parent feature may depend on its own sub-features (`feature-project` → `feature-project-create`), but one feature must never reach into an *unrelated* feature's internals. If two features need to share code, that shared code moves **down** into `core-*` (or `platform-*` if it's platform-bound) — it does not travel sideways.

### `apps/*` — the deployable apps

The `apps/*` entries are the deployable targets, and the top of the graph:

| App | Stack | Holds |
| --- | --- | --- |
| `mobile` | Expo / React Native | native navigation, mobile shell, device wiring |
| `web` | Next.js | routing/pages, web shell, SSR concerns |
| `backend` | API / server | server entrypoint, deployment wiring |
| `e2e` | Detox / Playwright | end-to-end tests across the apps |

An app is a **composition root**: it imports features, mounts them into routes/screens, and supplies the final platform wiring. It should be thin — mostly wiring, little logic. Nothing depends on an app; apps are the top of the graph and the leaves of the dependency tree. Apps are **not** prefixed — they're just `mobile`, `web`, `backend`, `e2e`.

## Dependency Direction (Strict)

Dependencies flow in exactly one direction:

```
apps/*  →  feature-*  →  platform-*  →  core-*
```

A package may depend on **any layer below it** and may skip a layer (a feature that needs no native code depends on `core-*` directly), but it must **never point upward**.

- `core-*` never imports `platform-*`, `feature-*`, or an app.
- `platform-*` composes `core-*` (and sibling `platform-*`); never a feature or app.
- `feature-*` composes `core-*` and `platform-*`; it never reaches into another feature's internals (only its own sub-features).
- `apps/*` compose `feature-*`, `platform-*`, and `core-*`.
- No circular dependencies, ever — not between packages, not between features.

```jsonc
// Bad — a core package reaching UP into a feature (arrow points the wrong way)
// packages/core-ui/package.json
{
  "name": "@hogwarts/core-ui",
  "dependencies": {
    "@hogwarts/feature-sorting-hat": "workspace:*", // core must not know features
    "@hogwarts/core-utils": "workspace:*"
  }
}
```

```jsonc
// Good — the feature depends downward on core and platform; both stay pure foundation
// packages/feature-sorting-hat/package.json
{
  "name": "@hogwarts/feature-sorting-hat",
  "dependencies": {
    "@hogwarts/core-ui": "workspace:*",
    "@hogwarts/core-hooks": "workspace:*",
    "@hogwarts/platform-ui": "workspace:*"
  }
}
```

If a feature needs logic from another feature, that is the signal to push the shared logic **down** into `core-*` (or `platform-*` if it's platform-bound), never to add a sideways `feature → feature` edge.

## Package Boundaries & Public API

Every package is a **black box**. It exposes its public API through a single entry point — its root `index.ts`, declared in `package.json` `exports` — and everything else is private. Consumers import from the **package name**, never from a file path inside it.

```jsonc
// packages/feature-quidditch/package.json — the entry point IS the public API
{
  "name": "@hogwarts/feature-quidditch",
  "private": true,
  "type": "module",
  "exports": { ".": "./index.ts" }
}

From hzblj/skills, MIT.

More from hzblj/skills