Wellness Link - Full-Stack Monorepo Expert

Expert for the wellness-link monorepo. Combines frontend (React 19 + Tailwind v4 + shadcn/ui) and backend (Bun + Elysia + Drizzle) development with monorepo-specific workflows.

Available Documentation

Patterns

• Full-Stack Workflow - Complete guide for implementing features across packages
• Monorepo Commands - Bun workspace commands, development, and troubleshooting

Agent References

• Web Agent - Quick reference to .claude/agent/web.md
• API Agent - Quick reference to .claude/agent/api.md

Monorepo Structure

wellness-link/
├── packages/
│   ├── web/          # React 19 + Vite (port 5176)
│   └── api/          # Bun + Elysia (port 5300)
├── bunfig.toml       # Bun workspaces
└── package.json      # Root workspace

Critical Cross-Package Rules

1. Type Sharing

typescript
1// API defines types, web imports via edenTreaty
2// packages/api/src/index.ts
3export const app = new Elysia()...
4
5// packages/web/src/lib/api.ts
6import type { App } from "@wellness-link/api"
7export const api = edenTreaty<App>("http://localhost:5300")

2. Language & Theme

• User-facing text: Spanish (buttons, forms, messages)
• Technical docs: English (code, comments, README)
• Theme: Always use CSS variables (bg-background, text-foreground)

3. Workspace Commands

bash
1# Run from root
2bun --filter @wellness-link/web dev    # Frontend only
3bun --filter @wellness-link/api dev    # Backend only
4
5# Development (both in parallel)
6bun run dev                             # Runs both packages

Web Package (packages/web)

Stack

• React 19 + React Router 7 (file-based)
• Tailwind CSS v4 + shadcn/ui
• TanStack Query (server state)
• React Hook Form + Zod (forms)

Critical Rules

typescript
1// ALWAYS use @/ alias
2import { Button } from "@/components/ui/button"
3import { cn } from "@/lib/utils"
4
5// ALWAYS use cn() for classes
6<div className={cn("flex", className, isActive && "bg-primary")} />
7
8// ALWAYS Spanish UI text
9<Button>Guardar Cambios</Button>
10toast.success("Perfil actualizado")

Data Fetching

typescript
1const { data, isLoading } = useQuery({
2  queryKey: ["profiles"],
3  queryFn: async () => {
4    const { data, error } = await api.api.profiles.get()
5    if (error) throw error
6    return data
7  },
8})

API Package (packages/api)

Stack

• Bun (runtime)
• Elysia (framework)
• Drizzle ORM (PostgreSQL)
• Better Auth (authentication)

Critical Rules

typescript
1// Table names are SINGULAR
2import { profile, asset, socialLink } from "../../db/schema"
3
4// ALWAYS register services in plugins/services.ts
5export const servicesPlugin = new Elysia({ name: "services" }).derive(
6  { as: "global" },
7  async () => {
8    const featureRepo = new FeatureRepository();
9    const featureService = new FeatureService(featureRepo);
10    return { services: { featureRepo, featureService } };
11  },
12);
13
14// Access relations via name
15const platform = click.socialLink.platform; // ✅
16const platform = click.platform;            // ❌

Route Pattern

typescript
1export const featureRoutes = new Elysia({ prefix: "/feature" })
2  .use(errorMiddleware)
3  .use(servicesPlugin)
4  .use(authGuard)
5  .get("/", ({ ctx, services }) => services.featureService.getAll(ctx!))
6  .post("/", ({ body, ctx, services, set }) => {
7    set.status = 201;
8    return services.featureService.create(ctx!, body);
9  }, { body: t.Object({ name: t.String() }) });

Full-Stack Feature Workflow

1. Define API Contract

typescript
1// packages/api/src/api/routes/feature.ts
2export const featureRoutes = new Elysia({ prefix: "/feature" })
3  .get("/", () => [...])
4  .post("/", ({ body }) => body, {
5    body: t.Object({
6      name: t.String(),
7      description: t.String(),
8    })
9  });

2. Add Route to App

typescript
1// packages/api/src/index.ts
2import { featureRoutes } from "./api/routes/feature"
3
4export const app = new Elysia()
5  .use(featureRoutes)
6  ...

3. Frontend Integration

typescript
1// packages/web/src/hooks/use-features.ts
2export function useFeatures() {
3  return useQuery({
4    queryKey: ["features"],
5    queryFn: async () => {
6      const { data, error } = await api.api.feature.get()
7      if (error) throw error
8      return data
9    },
10  })
11}
12
13// packages/web/src/components/FeatureForm.tsx
14const mutation = useMutation({
15  mutationFn: async (values: { name: string; description: string }) => {
16    const { data, error } = await api.api.feature.post(values)
17    if (error) throw error
18    return data
19  },
20})

Common Patterns

Authentication Flow

typescript
1// API: Better Auth automatic
2// packages/api/src/lib/auth.ts
3export const auth = betterAuth({ ... })
4
5// Web: Use auth client
6// packages/web/src/hooks/use-auth.ts
7const { data: session } = useSession()

File Upload (Full-Stack)

typescript
1// API: Asset service
2const asset = await services.assetService.create(ctx, {
3  file: request.file,
4  type: "avatar",
5})
6
7// Web: Form with file input
8const { mutate } = useMutation({
9  mutationFn: async (file: File) => {
10    const formData = new FormData()
11    formData.append("file", file)
12    const { data } = await api.api.assets.post(formData)
13    return data
14  },
15})

Error Handling

typescript
1// API: HTTP exceptions
2throw new NotFoundException("Profile not found")     // 404
3throw new ConflictException("Username exists")       // 409
4
5// Web: React Query + toast
6onError: (error) => {
7  toast.error(error.message || "Error al guardar")
8}

Monorepo Best Practices

1. Development Setup

bash
1# Install all dependencies
2bun install
3
4# Start both packages
5bun run dev
6
7# Type check entire monorepo
8bun run typecheck

2. Database Migrations

bash
1# Generate migration
2cd packages/api && bun run db:generate
3
4# Apply migration
5bun run db:migrate
6
7# Seed data
8bun run db:seed

3. Cross-Package Changes

Order: API first, then Web

1. Add DB schema/migration
2. Create repository + service
3. Add API route
4. Create frontend hook
5. Build UI component

4. Type Safety

typescript
1// API exports App type
2export type App = typeof app
3
4// Web imports and uses it
5import type { App } from "@wellness-link/api"
6export const api = edenTreaty<App>("http://localhost:5300")

Key Tables

• user: Better Auth authentication
• profile: Wellness professional info
• socialLink: Orderable social media links
• healthSurvey: Visitor survey responses
• analytics: Views and clicks tracking
• asset: File uploads (avatars, images)

Quick Commands

bash
1# Web development
2cd packages/web
3bun run dev          # Port 5176
4bun run build
5bun run lint
6
7# API development
8cd packages/api
9bun run dev          # Port 5300
10bun run db:seed
11bun run db:reset
12bun run lint
13
14# Monorepo (from root)
15bun run dev          # Both packages
16bun install          # All dependencies

When to Use This Skill

• Implementing features that span both web and api
• Setting up new API endpoints with frontend integration
• Working with shared types across packages
• Monorepo workflow questions
• Cross-package refactoring
• Full-stack feature development