Project Structure

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

Overall Structure

📁myapp/ - Sonamu monorepo root

📁node_modules/

📁packages/

📁api/ - Backend API server

📁web/ - Frontend web application

📄GITIGNORE.gitignore

📄YAMLpnpm-lock.yaml

📄YAMLpnpm-workspace.yaml - Workspace and dependency catalog

📄MDREADME.md - Project documentation

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/

📁src/ - Source code

📁database/ - Database related files

📄JSONpackage.json - Dependencies and scripts

📄TSvitest.config.ts - Test configuration

📄JSONtsconfig.json - TypeScript configuration

📄JSONtsconfig.schemas.json - Schema generation config

📄JSONtsconfig.types.json - Type generation config

📄TScustom-sequencer.ts - Test sequencer

📄SWCRC.swcrc - SWC compiler configuration

📄ENV.env - Environment variables (auto-generated)

Key File Descriptions

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/

📄TSindex.ts - Server entry point

📄TSsonamu.config.ts - Sonamu configuration file

📁application/ - Per-entity folders (auto-generated)

📁{entity}/

📄JSON{entity}.entity.json - Entity definition

📄TS{entity}.model.ts - Business logic

📄TS{entity}.types.ts - Types + Zod schemas

📄TS{entity}.model.test.ts - Tests (optional)

📄TSsonamu.generated.ts - Base schemas (auto-generated)

📁i18n/ - Internationalization

📄TSko.ts - Korean translations

📄TSen.ts - English translations

📁migrations/ - DB migration files

📁testing/ - Test configuration

📄TSglobal.ts - Global test setup

📄TSfixture.ts - Fixture management

📄TSsetup-mocks.ts - Mock setup

📁typings/ - Type definitions

📄TSsonamu.d.ts - Sonamu global types

📄TSfastify.d.ts - Fastify extension types

📁utils/ - Utility functions

📄TSsubset-loaders.ts - Subset loaders

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.

Key Directory Descriptions

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
What Gets Generated - Which files are auto-generated
Writing Tests - Test file structure

database/ Directory

📁packages/api/database/

📄YMLdocker-compose.yml - PostgreSQL container configuration

📁fixtures/

📄SHinit.sh - Database initialization script

📁dumps/ - Data dump files

📁scripts/

📄SHdump.sh - Data backup script

📄SHseed.sh - Data restore script

Key File Descriptions

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/

📁src/ - Source code

📄HTMLindex.html - HTML entry point

📄JSONpackage.json - Dependencies and scripts

📄TSvite.config.ts - Vite configuration

📄TStailwind.config.ts - Tailwind CSS configuration

📄JSONtsconfig.json - TypeScript configuration

📄JSONtsconfig.node.json - Node environment config

📄ENV.sonamu.env - Environment variables

Key File Descriptions

vite.config.ts

Vite development server configuration
TanStack Router, Tailwind CSS v4, unplugin-icons plugins
API proxy settings (/api → http://localhost:1028)
SSR configuration included

tailwind.config.ts

Tailwind CSS v4 configuration

.sonamu.env

API server connection information
API_HOST, API_PORT settings

src/ Directory

📁packages/web/src/

📄TSXentry-client.tsx - Client entry point

📄TSXentry-server.generated.tsx - SSR entry point (auto-generated)

📄TSXApp.tsx - Root component

📄TSrouteTree.gen.ts - Route tree (auto-generated)

📁routes/ - TanStack Router based pages

📄TSX__root.tsx - Root layout

📄TSXindex.tsx - Home page

📁services/ - API services (auto-generated)

📁{entity}/ - Per-entity services

📄TS{entity}.service.ts

📄TSsonamu.generated.ts

📄TSsonamu.shared.ts

📄TSservices.generated.ts

📁contexts/ - React Context

📄TSXSonamuContext.tsx - Sonamu Provider

📁i18n/ - Internationalization

📄TSko.ts

📄TSen.ts

📁admin-common/ - Common components

📄TSXApiLogViewer.tsx

📁components/ - UI components

📁styles/ - Style files

📄TSvite-env.d.ts - Vite type definitions

Key Directory Descriptions

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:

📁packages/api/src/application/

📁user/

📄JSONuser.entity.json - Created in Sonamu UI

📄TSuser.model.ts - Manually written

📄TSuser.types.ts - Auto-generated (extensible)

📄TSuser.model.test.ts - Manually written (optional)

📄TSsonamu.generated.ts - Auto-updated

📁packages/api/src/migrations/

📄SQL20250106120000_create_user.sql - Auto-generated

📁packages/web/src/services/

📁user/

📄TSuser.service.ts - Auto-generated

Role of Each File

{
  "properties": [
    {
      "name": "id",
      "type": "int",
      "isPrimary": true
    },
    {
      "name": "email",
      "type": "varchar"
    },
    {
      "name": "name",
      "type": "varchar"
    }
  ]
}

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 - How to write entity.json
@api Decorator - Defining APIs in model.ts
Entity Types - Using types.ts
Generated Types - Understanding sonamu.generated.ts

Key Work Locations During Development

Task	Location	Method
Entity Definition	`packages/api/src/application/{entity}/{entity}.entity.json`	Sonamu UI
Business Logic	`packages/api/src/application/{entity}/{entity}.model.ts`	Manual writing
Custom Types	`packages/api/src/application/{entity}/{entity}.types.ts`	Manual extension
API Endpoints	`@api` decorator in Model file	Manual writing
Database Config	`packages/api/src/sonamu.config.ts`	Manual writing
Server Config	`packages/api/src/sonamu.config.ts`	Manual writing
Writing Tests	`packages/api/src/application/{entity}/{entity}.model.test.ts`	Manual writing
Page Components	`packages/web/src/routes/`	Manual writing
Common Components	`packages/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.

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ