Frontend Docs
Frontend Folder Architecture
This page explains how the frontend project is organized, why each folder exists, and how the structure helps MyAwesomePOS stay clean, scalable and easy to maintain.
Purpose of this structure
The goal of the frontend architecture is simple: every file should have a clear place. Pages should live in the pages directory, layouts should wrap shared page structure, components should be reusable, and global styles should remain centralized.
A good folder architecture prevents chaos when the project grows. It also makes onboarding easier because another developer can understand the project without asking where everything is.
Pages
Pages define the public routes of the website. In Astro, the file system controls routing, so every page file usually represents a URL.
Layouts
Layouts wrap pages with shared structure such as header, footer, SEO metadata and common containers.
Components
Components contain reusable interface blocks like cards, navigation items, buttons, sections and documentation blocks.
Recommended folder structure
This is a practical structure for MyAwesomePOS. It is simple enough for the current stage, but strong enough to scale later.
src/
├── components/
│ ├── Header.astro
│ ├── Footer.astro
│ └── DocCard.astro
│
├── layouts/
│ └── MainLayout.astro
│
├── pages/
│ ├── index.astro
│ ├── download.astro
│ └── docs/
│ ├── index.astro
│ └── frontend/
│ ├── index.astro
│ ├── folder-architecture.astro
│ ├── reusable-components.astro
│ ├── neo-brutalism.astro
│ ├── routing.astro
│ └── build-deployment.astro
│
└── styles/
└── global.cssFolder responsibilities
| Folder | Responsibility | Example |
|---|---|---|
| components | Reusable visual pieces | Header, Footer, Cards |
| layouts | Shared page structure | MainLayout.astro |
| pages | Public routes | /docs/frontend/ |
| styles | Global CSS and design tokens | global.css |
Good practices
- Keep routes predictable. Use clear names that match the content of the page.
- Avoid duplicated layout code. Shared page structure should live in layouts.
- Extract repeated interface blocks. If the same UI appears several times, turn it into a component.
- Keep global styles controlled. Do not throw random styles everywhere without a clear reason.
Expandable notes
Why does Astro use file-based routing?
Astro creates routes based on the files inside the pages directory. This makes navigation simple because the URL structure is visible directly in the project tree.
Should every section become a component?
No. Only repeated or meaningful blocks should become components. Creating too many tiny components too early can make the project harder to read.
Where should page-specific styles go?
If a style is only used by one page, it can live inside that page. If it becomes reusable, move it to the global stylesheet or extract a component.
Important warning
Do not over-engineer the frontend too early
The architecture should help the project, not slow it down. For the current version of MyAwesomePOS, a clean Astro structure with pages, layouts, components and global styles is enough.
Final recommendation
Start simple. Keep pages clear, layouts centralized, and components reusable only when repetition appears. This gives the project a strong structure without turning the frontend into unnecessary complexity.