project-structure_skill

Overview

This skill standardizes Grey Haven project layouts for TanStack Start + React frontends and FastAPI + Python backends. It provides clear directory layouts, naming conventions, import patterns, and layer separation to speed project setup, refactoring, and team onboarding. Use it to maintain consistency across Claude Code agents, commands, and configs in the repo.

How this skill works

The skill inspects your project and compares its structure to the Grey Haven frontend and backend templates. It highlights missing folders, incorrect naming, import style issues, and deviations from recommended patterns (path aliases, component order, tenant isolation). It then suggests concrete fixes and a checklist to align files and code with the standard layout.

When to use it

• Creating a new Grey Haven frontend (TanStack Start + React) or backend (FastAPI + Python) project
• Organizing files in an existing project or enforcing repo-wide consistency
• Refactoring project layout to improve maintainability or onboarding
• Adding new routes, components, models, or services and deciding their location
• Preparing a project for CI/CD, testing, or deployments

Best practices

• Frontend: use the ~/* path alias for all internal TypeScript imports — never relative traversals
• Follow file naming rules: Components in PascalCase, modules and schemas in snake_case, routes lowercase with hyphens
• Organize component files with imports → types → component → hooks → handlers → JSX
• Backend: keep clear layers — routers → services → repositories → models → schemas → utils
• Implement tenant isolation at repository level and keep DB schema fields in snake_case
• Segment tests into unit/, integration/, and e2e/ and tag accordingly

Example use cases

• Bootstrapping a new TanStack Start app with preconfigured routes, UI, and auth
• Scaffolding a FastAPI service with routers, services, SQLModel models, and Alembic migrations
• Refactoring a monolithic repo into layered backend modules with repository patterns
• Onboarding new engineers by providing a consistent project layout and checklists
• Validating CI/CD and linting setups (Ruff, mypy, Vitest, Playwright) against templates