Development Cycle Overview
Sonamu development follows this cycle:Step 1: Entity Design and Definition
Create Entity in Sonamu UI
Development always starts by defining entities in Sonamu UI.- Add new entity in Entity tab
- Define fields - Set types, constraints, default values
- Define Subsets - Define API response formats
- Define Enums - Define sorting/search options
- Define Relations - Set relationships with other entities
- 1. Create Entity
- 2. Add Basic Fields
- 3. Field Details
- 4. Define Subsets
- 5. Define Enums
- 6. Define Relations
- Result

Create Entity via CLI (Optional)
You can also use the CLI to create an empty entity:Learn More
- Defining Entities - Entity structure and configuration options
- Using Sonamu UI - Managing entities in the UI
- Field Types - All available field types
- Defining Relations - Setting up entity relationships
- Defining Enums - Managing enumeration types
- Entity Management - Sonamu UI Entity tab guide
Step 2: Migration
Apply the entity definition to the database.Migration in Sonamu UI
- Click Migration tab
- Generate Migration - Auto-generate SQL
- Review generated SQL
- Run Migration - Apply to database
Migration via CLI (Optional)
Learn More
- How Migrations Work - Understanding the migration system
- Creating Migrations - SQL auto-generation mechanism
- Running Migrations - Safe migration execution
- Migration Tab - Managing migrations in Sonamu UI
- migrate CLI - Controlling migrations via CLI
Step 3: Scaffolding
After migration, auto-generate Model and test files.Scaffolding in Sonamu UI
- Click Scaffolding tab
- Select entity
- Select templates to generate:
- Model - Business logic and API endpoints
- Model Test - Test file
- Preview (optional) - Preview code to be generated
- Generate - Create files
Scaffolding via CLI (Optional)
Generated Files
{entity}.model.ts- Includes basic CRUD APIs{entity}.model.test.ts- Test template
Learn More
- Scaffolding Tab - Generating code in UI
- scaffold CLI - File scaffolding via CLI
- Test Scaffolding - Auto-generating test files
Step 4: Business Logic Implementation
Add business logic to the generated Model files.Model File Structure
user.model.ts
API Decorator
The@api decorator automatically registers methods as REST API endpoints:
HMR (Hot Module Replacement)When you modify Model files, the API server automatically restarts. No manual server restart needed!
Learn More
- What is a Model? - Role and structure of Models
- @api Decorator - Auto-generating API endpoints
- Writing Business Logic - Implementing logic in Models
- BaseModel Methods - Built-in CRUD methods
- Creating APIs - Detailed API development guide
- Puri Query Builder - Writing type-safe queries
- Transactions - Safe data handling
Step 5: Synchronization (Sync)
Synchronize changes with the frontend.Auto Sync (HMR)
When running the dev server withpnpm dev, file changes are automatically synchronized:
- ✅ Model file change → Service file auto-regenerated
- ✅ Types file change → Auto-copied to Web project
- ✅ Entity definition change → Schema auto-regenerated
Manual Sync
You can manually sync if needed:pnpm sync performs the following tasks:
- Copy sonamu.shared.ts - Copy common types and utilities to Web
- Detect changed files - Check changed files based on checksums
- Type sync - Copy
*.types.ts,*.generated.tsfiles to Web - Generate Services - Generate frontend Services based on Model APIs
- Config sync - Update
.sonamu.envfile
When Sync Command is Needed
- When you’ve modified multiple files with the dev server stopped
- When switching branches in Git
- When you think the sync state is broken
Learn More
- Understanding Syncer - Detailed synchronization mechanism
- What Gets Generated - Which files are generated
- How HMR Works - Understanding Hot Module Replacement
Step 6: Testing
Test the business logic you’ve written.Writing Test Files
Add test cases to the test file generated by scaffolding:user.model.test.ts
Running Tests
Learn More
- Writing Tests - Vitest-based test structure
- Test Scaffolding - Using test templates
- Creating Fixtures - Managing test data
- What is Naite? - Test logging system
Step 7: Frontend Integration
Implement UI using the auto-generated Services.Generated Service Files
APIs defined in Models are automatically generated as frontend Services:web/src/services/UserService.ts (auto-generated)
Using in React Components
web/src/pages/UserProfile.tsx
Type SafetyServices and types are auto-synchronized with the backend, so type mismatch errors can be caught at compile time!
Learn More
- How Services Work - Auto-generation mechanism
- Using Services - Practical usage guide
- Shared Types - Backend-frontend type synchronization
Complete Workflow Example
Let’s look at an example of the complete process of adding a feature.Scenario: Adding “Like” Feature
Development Tips
1. Entity First Principle
All development starts with entity definition. Clear data structures lead to clear APIs and UIs.2. Utilize Subsets
Pre-defining various Subsets can optimize API response sizes:- A (All): All fields (detail page)
- C (Compact): Main fields only (list page)
- S (Summary): Minimal fields (preview)
3. Relation Design
Clearly defining relationships between entities auto-generates JOIN queries.4. Test-First Development
For complex business logic, writing tests first enables safer development.5. Utilize HMR
During development, keeppnpm dev running and just modify files - they’ll sync automatically.
6. When Problems Occur
If sync state seems wrong:- Restart dev server
- Run
pnpm syncmanually - Delete
sonamu.lockand restart





