01-house-style/03-directory-structure.md

Directory structure

Directory structure

Vroq apps should follow a consistent directory structure so ChatGPT and humans can quickly understand where code belongs.

This structure groups code by responsibility and by feature.

Standard structure

Typical Vroq app layout:

app/
  index.html
  App.js

  shared/
    store/
      configureStore.js
      initialState.js

    api/

    ui/

  features/
    featureName/
      index.js
      featureActions.js
      featureReducer.js
      FeatureSection.js
      apiClient.js
      components/
      sections/

Root files

index.html

Responsible only for bootstrapping the app and loading the Vroq runtime and App.js.

It should stay small and contain no application logic.

App.js

The root UI composition file.

Responsibilities:

• initialize the store
• mount the root app
• compose top-level sections

App.js should not contain large feature logic.

shared/

Shared code that is reused across multiple features.

Examples:

• store setup
• API helpers used by multiple features
• shared UI helpers

Avoid putting feature-specific logic in shared/.

features/

Each feature folder owns a coherent part of the application.

Typical contents:

• reducer
• actions
• UI sections
• feature-specific API client

Example:

features/files/
  index.js
  filesReducer.js
  filesActions.js
  FileListSection.js
  fileApi.js

components vs sections

Components:

• reusable UI units
• mostly presentation logic
• minimal knowledge of the store

Sections:

• feature-local UI fragments
• usually connected to store state

Sections belong inside feature folders.

Final rule

A reader should be able to locate feature logic by navigating the feature folder, not by searching the entire project.