tailscale-custom/.agent/skills/app-builder/scaffolding.md

Project Scaffolding

Directory structure and core files for new projects.

---

Next.js Full-Stack Structure (2025 Optimized)

project-name/
├── src/
│   ├── app/                        # Routes only (thin layer)
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── globals.css
│   │   ├── (auth)/                 # Route group - auth pages
│   │   │   ├── login/page.tsx
│   │   │   └── register/page.tsx
│   │   ├── (dashboard)/            # Route group - dashboard layout
│   │   │   ├── layout.tsx
│   │   │   └── page.tsx
│   │   └── api/
│   │       └── [resource]/route.ts
│   │
│   ├── features/                   # Feature-based modules
│   │   ├── auth/
│   │   │   ├── components/
│   │   │   ├── hooks/
│   │   │   ├── actions.ts          # Server Actions
│   │   │   ├── queries.ts          # Data fetching
│   │   │   └── types.ts
│   │   ├── products/
│   │   │   ├── components/
│   │   │   ├── actions.ts
│   │   │   └── queries.ts
│   │   └── cart/
│   │       └── ...
│   │
│   ├── shared/                     # Shared utilities
│   │   ├── components/ui/          # Reusable UI components
│   │   ├── lib/                    # Utils, helpers
│   │   └── hooks/                  # Global hooks
│   │
│   └── server/                     # Server-only code
│       ├── db/                     # Database client (Prisma)
│       ├── auth/                   # Auth config
│       └── services/               # External API integrations
│
├── prisma/
│   ├── schema.prisma
│   ├── migrations/
│   └── seed.ts
│
├── public/
├── .env.example
├── .env.local
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── README.md

---

Structure Principles

Principle	Implementation
Feature isolation	Each feature in features/ with its own components, hooks, actions
Server/Client separation	Server-only code in server/, prevents accidental client imports
Thin routes	app/ only for routing, logic lives in features/
Route groups	(groupName)/ for layout sharing without URL impact
Shared code	shared/ for truly reusable UI and utilities

---

Core Files

File	Purpose
package.json	Dependencies
tsconfig.json	TypeScript + path aliases (@/features/*)
tailwind.config.ts	Tailwind config
.env.example	Environment template
README.md	Project documentation
.gitignore	Git ignore rules
prisma/schema.prisma	Database schema

---

Path Aliases (tsconfig.json)

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/features/*": ["./src/features/*"],
      "@/shared/*": ["./src/shared/*"],
      "@/server/*": ["./src/server/*"]
    }
  }
}

---

When to Use What

Need	Location
New page/route	app/(group)/page.tsx
Feature component	features/[name]/components/
Server action	features/[name]/actions.ts
Data fetching	features/[name]/queries.ts
Reusable button/input	shared/components/ui/
Database query	server/db/
External API call	server/services/