Site Diary Monorepo Development

This skill provides guidance for working with a Yarn v1 monorepo containing a React Native/Expo mobile app and a Next.js web app with a GraphQL API backend for site diary management.

Project Structure

The monorepo uses Yarn workspaces with two main apps:

```

apps/

mobile/ # React Native/Expo mobile app with GraphQL client

web/ # Next.js app with GraphQL API server (Grats-based)

packages/

eslint-config/ # Shared ESLint configuration

```

Prerequisites

Before starting development:

Development Workflow

Initial Setup

1. Install all dependencies across the monorepo:

```bash

yarn install

```

Working with the Web App (GraphQL Backend)

The web app uses **Grats** for code-first GraphQL schema generation. The schema is auto-generated from JSDoc decorators.

**Start the development server:**

```bash

yarn dev:web

Or: yarn workspace @untitled/web dev

```

The GraphQL API will be available at: `http://localhost:3000/api/graphql`

**When modifying the GraphQL schema:**

1. Edit resolvers in `src/app/api/graphql/query.ts` or `mutation.ts` using `@gql*` JSDoc decorators

2. Regenerate the schema file:

```bash

yarn workspace @untitled/web grats

```

3. **IMPORTANT**: The mobile app codegen depends on this schema, so regenerate mobile types after schema changes

**Other web commands:**

Working with the Mobile App

The mobile app uses **Apollo Client** to consume the GraphQL API and **Expo Router** for file-based navigation.

**First-time setup (native builds):**

```bash

yarn workspace @untitled/mobile prebuild

yarn workspace @untitled/mobile ios # For iOS simulator

yarn workspace @untitled/mobile android # For Android emulator

```

**Start development (after prebuild):**

```bash

yarn dev:mobile

Or: yarn workspace @untitled/mobile dev

```

**Regenerate GraphQL types from web API:**

⚠️ **CRITICAL**: The web server must be running at `http://localhost:3000/api/graphql` before running codegen.

```bash

yarn workspace @untitled/mobile codegen

```

This generates TypeScript types in `src/types/__generated__/graphql.ts` from the web API schema.

**Other mobile commands:**

GraphQL Schema Change Workflow

When you need to modify the GraphQL API:

1. **Start web server** (mobile codegen requires it): `yarn dev:web`

2. **Modify resolvers** in `apps/web/src/app/api/graphql/` using Grats JSDoc decorators

3. **Regenerate schema**: `yarn workspace @untitled/web grats`

4. **Update mobile types**: `yarn workspace @untitled/mobile codegen`

5. **Verify types** in both workspaces

Monorepo-Wide Commands

Run quality checks across all workspaces:

```bash

yarn ci # Run all CI checks (format, lint, typecheck)

yarn format # Format all code with Prettier

yarn format-check # Check formatting without modifying

yarn lint # Run ESLint across all workspaces

yarn typecheck # Run TypeScript checking across all workspaces

yarn sherif-check # Check dependency consistency

yarn sherif # Fix dependency inconsistencies

```

Architecture Notes

Web App (Backend)

- Resolvers use `@gql*` JSDoc decorators

- Schema auto-generated in `schema.ts` (do not edit manually)

- GraphQL Yoga serves the API at `/api/graphql`

Mobile App (Client)

Shared Stack

Important Constraints

1. **Schema changes must go through Grats** - never edit `schema.ts` manually

2. **Web server must be running** before mobile codegen (`http://localhost:3000/api/graphql`)

3. **Both apps use React 19.1** via yarn resolutions

4. **Mobile routes use Expo Router** with tabs in `src/app/(tabs)`

5. **Run prebuild once** for native builds, then use `dev:mobile` for subsequent sessions

Troubleshooting

**Mobile codegen fails:**

**Type errors after schema changes:**

**Dependency issues:**

Example Tasks

Adding a new GraphQL query

1. Start web server: `yarn dev:web`

2. Edit `apps/web/src/app/api/graphql/query.ts` with Grats decorators

3. Regenerate schema: `yarn workspace @untitled/web grats`

4. Regenerate mobile types: `yarn workspace @untitled/mobile codegen`

5. Use the new query in mobile app with full type safety

Making mobile UI changes

1. Start web server: `yarn dev:web`

2. Start mobile dev: `yarn dev:mobile`

3. Edit components in `apps/mobile/src/app/(tabs)`

4. Use NativeWind classes for styling

5. Test in iOS/Android simulators

Running full quality checks

```bash

yarn ci # Runs format-check, lint, and typecheck across all workspaces

```