Skip to main content
A Modelence project follows a well-organized structure that clearly separates client and server code, making it easy to build full-stack applications with TypeScript.

​
Directory Overview

When you create a new Modelence project, you’ll see the following structure: 
my-app/
├── src/
│   ├── client/          # Frontend code
│   ├── server/          # Backend code
│   └── shared/          # (Optional) Shared code
├── assets/              # Static assets (images, fonts)
├── .modelence.env       # Generated by `npx modelence setup` (cloud connection)
├── package.json         # Project dependencies
└── tsconfig.json        # TypeScript configuration

​
Client Directory

The src/client directory contains all your frontend React application code.

​
Key Files

  • index.html - The main HTML template for your application. You typically don’t need to modify this file unless you want to add meta tags, external scripts, or customize the root template.
  • index.tsx - The React application entry point. This is where you initialize your client-side app using renderApp() and configure providers. 
    import { renderApp } from 'modelence/client';
import routes from './routes';
import './index.css';

renderApp({
  routes,
});
  • index.css - Global CSS styles for your application. This file typically includes Tailwind CSS imports and any global style customizations.
  • routes.ts - Client-side routing configuration that maps URL paths to React components. 
    import { createBrowserRouter } from 'react-router-dom';
import Home from './pages/Home';
import About from './pages/About';

export default createBrowserRouter([
  { path: '/', element: <Home /> },
  { path: '/about', element: <About /> },
]);

​
Organizing Client Code

Within the client directory, you can organize your code into subdirectories: 
src/client/
├── components/       # Reusable React components
├── pages/           # Page-level components
├── hooks/           # Custom React hooks
└── utils/           # Client-side utilities

​
Server Directory

The src/server directory contains all your backend code, including API logic, database models, and business logic.

​
Key Files

  • app.ts - The server entry point where you configure and start your Modelence application. 
    import { startApp } from 'modelence/server';
import todoModule from './todo';

startApp({
  modules: [todoModule],
});

​
Organizing Server Code by Modules

The recommended approach is to organize server code into modules - self-contained units of functionality: 
src/server/
├── migrations/       # (Optional) App migration scripts
│   ├── index.ts      # Exports the ordered migrations array
│   └── ...           # One file per migration handler
├── todo/
│   ├── index.ts      # Module definition
│   ├── db.ts         # Database stores
│   └── utils.ts      # Module utilities
├── users/
│   ├── index.ts
│   └── db.ts
└── app.ts            # Main server file
Each module typically contains:
  • Module definition - Queries, mutations, and configuration
  • Database stores - MongoDB collection definitions
  • Business logic - Domain-specific utilities and helpers
For data evolution over time, keep app-level migration scripts under src/server/migrations/ — one file per handler, with index.ts exporting the ordered array passed to startApp({ migrations }). See Migrations for the full layout.
Grouping code by modules (domains/features) rather than by type (controllers, models, etc.) makes your codebase more maintainable and easier to understand as it grows.

​
Shared Code

You can create a src/shared directory (or any other name) for code that needs to be used by both client and server: 
src/
├── client/
├── server/
└── shared/
    ├── types.ts      # Shared TypeScript types
    ├── constants.ts  # Shared constants
    └── utils.ts      # Shared utilities
Be careful when importing server code into client code or vice versa.

​
Configuration Files

​
.modelence.env

Environment-specific configuration for your application. This file should never be committed to version control. 
# MongoDB connection
MONGODB_URI="mongodb+srv://..."

# Other configuration
PORT=3000
Always add .modelence.env to your .gitignore file to prevent committing sensitive credentials.

​
package.json

Standard Node.js package configuration. Modelence projects include these key scripts: 
{
  "scripts": {
    "dev": "modelence dev",
    "build": "modelence build",
    "start": "node dist/server/app.js"
  }
}

​
tsconfig.json

TypeScript configuration for your project. Modelence sets up appropriate defaults for both client and server code with path aliases and module resolution.

​
Build Output

When you build your application with npm run build, Modelence generates a dist directory: 
dist/
├── client/          # Built frontend assets
│   ├── index.html
│   ├── assets/
│   └── ...
└── server/          # Compiled server code
    └── app.js
The built application is ready for deployment to any Node.js hosting platform.

​
Next Steps

Modules

Learn how to organize your application logic into modules

Configuration

Understand how to configure your Modelence application