Project structure

The scaffold keeps configuration at the project root and application code under src. Tavo.js gives two source locations special safety or routing behavior: src/pages defines the route tree, and src/server is blocked from client bundles. Other source folders are application organization.

textproject-dashboard/
├── public/                 static browser assets
├── src/
│   ├── pages/              file-based routes and layouts
│   ├── server/             enforced server-only modules, when needed
│   ├── components/         reusable interface and behavior
│   ├── store/              shared client state
│   ├── main.tsx            browser bootstrap
│   └── styles.css          application-wide styles
├── index.html              document shell
├── tavo.config.ts          framework and plugin settings
├── tavo-ui.config.ts       project theme input, after UI setup
├── tsconfig.json           TypeScript contract
└── vite.config.ts          build integration

Every non-underscore TypeScript or TSX module inside src/pages is treated as a route module. Normal folders add URL segments. Brackets create parameters, three dots create catch-all parameters, and parentheses group files without adding a public segment. A _layout.tsx file wraps its descendants.

Do not place ordinary helpers, services, stores, or components in src/pages with a normal filename: Tavo.js will try to load them as routes. Move them to another source folder, or use an underscore-prefixed private file only for a small route-local helper.

textindex.tsx                    → /
projects/index.tsx           → /projects
projects/[id].tsx            → /projects/:id
docs/[[...slug]].tsx         → /docs/*?slug
(marketing)/about.tsx        → /about
projects/_layout.tsx         → wraps /projects and descendants
projects/_format.ts          → private helper; not a route
projects/format.ts           → route module; do not use as a helper

src/pages and src/server have framework meaning. Names such as components and features do not: they are folders you create to make browser-safe and shared code easy to find.

Start with the simple structure below. A route file loads the data for its URL and assembles the page. Move code out of that file when it becomes reusable or when it must stay on the server.

• Used by one route? Keep it next to that route until the file becomes hard to read.

• Used by several routes? Move it to src/components, src/features, or another clearly named shared folder.

• Uses a database, secret, session, or private API key? Put it in src/server. Tavo.js treats that directory as server-only and blocks imports that reach a client bundle.

• Needed directly by the browser, such as an image or font? Put it in public; public/logo.svg is available at /logo.svg.

• Found in .tavo/build or .tavo/generated? Do not edit it. Tavo.js recreates generated files.

textsrc/
├── pages/
│   └── projects/
│       └── [id].tsx         route for /projects/:id
├── features/
│   └── projects/
│       └── ProjectCard.tsx  UI used by project routes
├── components/
│   └── PageHeader.tsx       UI reused across the app
└── server/
    └── projects.ts          database code; never imported by browser code

public/
└── logo.svg                 available in the app as /logo.svg

Use the CLI to inspect the route tree after adding or moving page files. The output should contain only URLs that the application intentionally exposes.

bashnpx tavo routes
npm run typecheck