Skip to main content
A Sonamu project is structured as a monorepo that manages both the backend (api) and frontend (web) together.

​
Overall Structure

Complete project structure

​
pnpm Workspace

The root pnpm-workspace.yaml manages packages and common dependency versions:
pnpm-workspace.yaml
packages:
  - packages/api
  - packages/web

catalog:
  "@tanstack/react-query": ^5.90.12
  "@tanstack/react-router": 1.143.11
  react: ^19.2.3
  vite: 7.3.0
  vitest: 4.0.16
  zod: ^4.1.12
  # ... other common dependencies

​
API Directory (Backend)

​
Root Files

packages/api directory structure
package.json
  • Backend dependency management
  • npm scripts: dev, build, test, docker:up/down, dump, seed, etc.
vitest.config.ts
  • Vitest test configuration
  • Sonamu-optimized settings via getSonamuTestConfig() function
  • Coverage, reporter, sequencer configuration
tsconfig.json
  • Main TypeScript compiler configuration
  • tsconfig.schemas.json: Dedicated for Zod schema generation
  • tsconfig.types.json: Dedicated for type definition generation
.env
  • Database connection info (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD)
  • Project configuration variables (DATABASE_NAME, CONTAINER_NAME, PROJECT_NAME)
  • Auto-generated when running pnpm create sonamu

​
src/ Directory

packages/api/src directory structure
Entity File Creation ProcessFiles in the application/{entity}/ folder are created when you create an entity through Sonamu UI and scaffold:
  • .entity.json: Auto-generated when defining entity in Sonamu UI
  • .model.ts: Generated via pnpm scaffold model or Sonamu UI’s Scaffolding tab
  • .types.ts: Auto-generated when saving entity
  • .model.test.ts: Generated via pnpm scaffold model_test or Sonamu UI’s Scaffolding tab (optional)
When you first create a project, the application/ folder is empty. The folder is created when you create your first entity.
application/
  • Auto-created when creating the first entity
  • Separate directory for each entity
  • Example: User entity β†’ application/user/ directory
application//.entity.json
  • Entity definition file
  • Created in Sonamu UI
  • Source of database schema
application//.model.ts
  • Business logic implementation
  • API endpoint definitions (@api decorator)
  • File you write directly
application//.types.ts
  • TypeScript type definitions
  • Zod validation schemas
  • Auto-generated but extensible
  • Shared with frontend
application/sonamu.generated.ts
  • Auto-generated Base schemas for all entities
  • Enum types and label definitions
  • Do not modify directly
i18n/
  • Internationalization translation files
  • ko.ts: Korean, en.ts: English
  • sd.generated.ts is auto-generated when adding entities
migrations/
  • DB migration files generated by Sonamu UI
  • Run with pnpm sonamu migrate run
testing/
  • Vitest test environment configuration
  • global.ts: Uses export { setup } from "sonamu/test" pattern
  • Fixture data management
Learn More - Entity Files - Defining Entities - How to write entity.json - Creating Models - model.ts writing guide - Type System - Understanding types.ts

​
database/ Directory

docker-compose.yml
  • PostgreSQL + pgvector image
  • Container name, port, environment variable configuration
  • Run with pnpm docker:up
fixtures/init.sh
  • Database initialization shell script
  • Installs pgvector extension and creates databases
  • Creates databases using environment variables (DATABASE_NAME, _fixture, _test)
  • Auto-generated when running pnpm create sonamu
dumps/
  • SQL files generated by pnpm dump command
  • Data backup storage
scripts/
  • dump.sh: Backs up current DB data to dumps/
  • seed.sh: Restores data from dumps/ to DB
Learn More - Configuration Files - sonamu.config.ts Settings - Overall project configuration - Database Configuration - DB connection and settings - Server Configuration - Fastify server settings - TypeScript Configuration - Compiler options - Environment Variables - .env file management

​
Web Directory (Frontend)

​
Root Files

packages/web directory structure
vite.config.ts
  • Vite development server configuration
  • TanStack Router, Tailwind CSS v4, unplugin-icons plugins
  • API proxy settings (/api β†’ http://localhost:34900)
  • SSR configuration included
tailwind.config.ts
  • Tailwind CSS v4 configuration
.sonamu.env
  • API server connection information
  • API_HOST, API_PORT settings

​
src/ Directory

routes/
  • TanStack Router based file system routing
  • __root.tsx: Global layout
  • Filenames map to URL paths
services/
  • Service layer for communicating with the API server
  • Auto-generated for each entity
  • TanStack Query integration support
contexts/
  • React Context Providers
  • SonamuContext: Global state management
i18n/
  • Frontend internationalization translation files
  • Synchronized with API’s i18n
admin-common/
  • Reusable common components
  • Debugging tools like ApiLogViewer
Learn More - Frontend - How Services Work - Auto-generation mechanism - Using Services - How to call APIs - Shared Types - Backend-frontend type synchronization

​
Example File Structure After Creating an Entity

When you create a User entity, the following structure is created:
user folder structure 1user folder structure 2

​
Role of Each File

{
  "properties": [
    {
      "name": "id",
      "type": "int",
      "isPrimary": true
    },
    {
      "name": "email",
      "type": "varchar"
    },
    {
      "name": "name",
      "type": "varchar"
    }
  ]
}
VS Code split view
Auto-generated vs Manually Written - .entity.json: Written in Sonamu UI - .model.ts: Manually written - .types.ts: Auto-generated but extensible - sonamu.generated.ts: Auto-generated - do not modify - {entity}.service.ts: Auto-generated - do not modify
Learn More - Per-File Guides - Defining Entities

​
Key Work Locations During Development

TaskLocationMethod
Entity Definitionpackages/api/src/application/{entity}/{entity}.entity.jsonSonamu UI
Business Logicpackages/api/src/application/{entity}/{entity}.model.tsManual writing
Custom Typespackages/api/src/application/{entity}/{entity}.types.tsManual extension
API Endpoints@api decorator in Model fileManual writing
Database Configpackages/api/src/sonamu.config.tsManual writing
Server Configpackages/api/src/sonamu.config.tsManual writing
Writing Testspackages/api/src/application/{entity}/{entity}.model.test.tsManual writing
Page Componentspackages/web/src/routes/Manual writing
Common Componentspackages/web/src/admin-common/Manual writing
Auto-generated File Cautions - sonamu.generated.ts: Never modify - {entity}.service.ts: Never modify - {entity}.types.ts: Extension is possible but do not modify auto-generated parts

​
Next Steps

Now that you understand the project structure, create your first entity:

Creating Your First Entity

Use Sonamu UI to create your first entity and define the database schema.

Development Workflow

Understand Sonamu’s complete development cycle and learn how to work efficiently.