alepha@docs:~/docs/concepts$
cat 7-project-structure.md1 min read
Last commit:
#Project Structure
Alepha is opinionated about how code runs, but fairly loose about how files are organized. However, we recommend a structure that scales well from small apps to large monoliths.
#The "Standard" Structure
When you run alepha init, we set up something like this:
bash
├── src/
│ ├── main.server.ts # Entry point for the backend
│ ├── main.browser.ts # Entry point for the frontend
│ ├── AppRouter.ts # Routes ($page) definition
│ │
│ ├── controllers/ # API Controllers ($action)
│ ├── services/ # Business Logic
│ ├── entities/ # DB Schemas ($entity)
│ ├── schemas/ # Validation Schemas (TypeBox)
│ ├── providers/ # Custom Providers
│ ├── atoms/ # Shared State ($atom)
│ │
│ ├── components/ # React Components
│ └── styles/ # CSS Styles
│
└── package.jsonThis is a minimalist structure for small projects. Alepha uses a layered organization by type—all controllers together, all entities together, etc.
#Scaling with Modules
As your project grows, add a module layer to group related features:
bash
├── src/
│ ├── main.server.ts
│ ├── main.browser.ts
│ │
│ ├── users/
│ │ ├── controllers/
│ │ ├── services/
│ │ ├── entities/
│ │ ├── schemas/
│ │ └── index.ts # UsersModule
│ │
│ ├── billing/
│ │ ├── controllers/
│ │ ├── services/
│ │ ├── entities/
│ │ ├── schemas/
│ │ └── index.ts # BillingModule
│ │
│ └── shared/
│ ├── components/
│ └── styles/
│
└── package.jsonEach module exports a $module that groups its services:
typescript
1// src/users/index.ts2export const MyappUsers = $module({3 name: "myapp.users",4 services: [5 UserController,6 UserService,7 // ...8 ]9});You can also separate by concern (frontend/backend):
bash
├── src/
│ ├── backend/
│ │ ├── controllers/
│ │ ├── services/
│ │ └── entities/
│ │
│ ├── frontend/
│ │ ├── components/
│ │ ├── atoms/
│ │ └── styles/
│ │
│ └── shared/
│ └── schemas/
│
└── package.jsonThe layered structure stays the same—you just add a directory level to organize by module or concern.
On This Page
No headings found...