Project Structure

!Note: this page is auto-generated from docs/project-structure.md.

Head Start is based on and extends the Astro project structure.

Inside of this project, you'll see the following folders and files:

/
├── config/
├── docs/
│   └── decision-log/
├── public/
│   └── favicon.svg
├── src/
│   ├── assets/
│   │   └── icons/
│   │       └── name.svg
│   ├── blocks/
│   │   ├── Blocks.astro
│   │   └── SomeContentBlock/
│   │       ├── SomeContentBlock.astro
│   │       └── SomeContentBlock.fragment.graphql
│   ├── components/
│   │   └── SomeUiComponent.astro
│   ├── layouts/
│   │   └── Default.astro
│   ├── lib/
│   │   └── some-helper-function.ts
│   ├── middleware/
│   │   └── some-req-res-interceptor.ts
│   └── pages/
│       ├── api/
|       |   └── some-dynamic-endpoint.ts
│       └── [locale]/
│           ├── index.astro
│           └── _index.query.graphql
└── package.json

• .agents/skills/ contains project-specific agent skills — reusable capability bundles loaded by AI agents on demand. See Working with AI.

• docs/ contains project documentation.

  • decision-log/ lists all key decisions made during the project. Please read the log so you understand why decisions are made and document key decisions when you make them.

  • The Editor Guide is displayed inside the CMS via the custom page plugin. Edit editor-guide.md to update the guide and submit those changes through a PR for review. Images for the guide go in public/editor-guide/ and can be referenced as ![alt](/editor-guide/filename.png). Preview changes locally at http://localhost:4323/cms/editor-guide/.

• src/ contains all website source files that will be handled by Astro.

  • pages/ - Pages are organised by file system routing and are paired with GraphQL query files for data loading.

  • pages/api/ - API routes are dynamic server endpoints with support for path & query params etc.

  • components/ - Components are the elements the website is composed of. This can be Astro and framework specific components.

  • blocks/ - Blocks are a specific set of components which have a complementary content Block in DatoCMS and therefore have a paired GraphQL fragment file.

  • layouts/ - Layouts are Astro components used to provide a reusable UI structure, such as a page template.

  • lib/ - Shared logic and utility helpers, like datocms, i18n and routing.

  • middleware - intercept and (possibly) transform requests & responses. See Astro middleware.

  • assets/ - is for assets that require a build step. See Assets.

• public/ is for any static assets that are served as-is. See Assets.

• config/ bundles all our configuration files (like DatoCMS migrations), so the project root doesn't become too cluttered.

• scripts/ contains all our custom CLI scripts, typically available via package.json > scripts. Also see Commands.