File Structure

Vla doesn’t enforce a specific file structure. You’re free to organize your code however you like. However, we recommend aligning your file structure with how Vla structures your code.

This page provides recommendations based on your app’s size and complexity.

File per Resource

For small apps or prototypes, keep it simple. A handful of files in a single folder is often enough.

Directorysrc/
- Directoryapp/ Your framework’s routes
  - …
- Directorydata/
  - users.ts
  - posts.ts
  - kernel.ts Kernel setup

Folder per Layer

When your app grows beyond a few classes, organize files by layer (Actions, Services, Repos) using naming conventions or folders.

Directorysrc/
- Directoryapp/
  - …
- Directorydata/
  - kernel.ts
  - db.ts
  - Directoryactions/
    listPosts.ts
    showPost.ts
    showUserProfile.ts
  - Directoryservices/
    postsService.ts
    usersService.ts
  - Directoryrepos/
    postsRepo.ts
    usersRepo.ts

Folder per Module

For large apps or teams, organize by modules to separate domains. Each module has its own directory with its layers inside.

Directorysrc/
- Directoryapp/
  - …
- Directorydata/
  - kernel.ts
  - Directoryresources/
    db.ts
    redis.ts
  - Directoryusers/
    user.module.ts
    user.facade.ts Public API for other modules
    user.actions.ts
    user.service.ts
    user.repo.ts
  - Directorybilling/
    billing.module.ts
    billing.facade.ts Public API for other modules
    invoice.actions.ts
    invoice.service.ts
    invoice.repo.ts
    subscription.service.ts
    subscription.repo.ts
  - Directoryanalytics/
    analytics.module.ts
    analytics.facade.ts Public API for other modules
    analytics.actions.ts
    analytics.service.ts
    analytics.repo.ts

Module Growth Patterns

As a module grows, you can further organize it internally.

Small Module

Keep everything flat within the module directory.

Directorydata/
- Directoryusers/
  - user.module.ts
  - user.actions.ts
  - user.service.ts
  - user.repo.ts
  - user.facade.ts

Group by Resource

Group by resource when the module has multiple resources.

Directorydata/
- Directorybilling/
  - billing.module.ts
  - billing.facade.ts
  - Directoryinvoice/
    invoice.service.ts
    invoice.repo.ts
  - Directorysubscription/
    subscription.service.ts
    subscription.repo.ts
  - Directorypayment/
    payment.service.ts
    payment.repo.ts

Group by Layer

Group by layer type when there are many files.

Directorydata/
- Directoryusers/
  - user.module.ts
  - user.facade.ts
  - auth.facade.ts
  - Directoryactions/
    user.actions.ts
    auth.actions.ts
    profile.actions.ts
  - Directoryservices/
    user.service.ts
    auth.service.ts
    profile.service.ts
  - Directoryrepos/
    user.repo.ts
    session.repo.ts
    profile.repo.ts

General Guidelines

Keep Resources Global

Resources like database clients are typically shared across modules, so keep them in a shared location.

Directorydata/
- Directoryresources/
  - db.ts
  - redis.ts
  - s3.ts
- Directoryusers/
  - …
- Directorybilling/
  - …

Migration Path

You don’t need to choose the “perfect” structure upfront. Start simple and evolve:

Start small - Single file or flat structure
Split when needed - Break out files as they grow
Group when clear - Add folders when grouping becomes obvious
Modules when scaling - Introduce modules when domains become distinct