Step 2 of 12 17% complete

Step 2: Project Structure and Configuration

What You'll Learn

Understand the NoEgo project directory structure
Learn about configuration files and their purposes
Explore the relationship between different components
Configure TypeScript and build settings

What You'll Build

A clear understanding of where to place different types of code.

Directory Structure

After creating your project, you'll see the following directory structure:

project structure

my-app/
├── src/
│   ├── index.ts              # App bootstrap (Express + logging)
│   ├── server/
│   │   ├── server.ts         # NoEgo server entry
│   │   ├── container.ts      # IoC container setup
│   │   ├── controller/       # HTTP controllers
│   │   ├── services/         # Business logic services
│   │   ├── repo/             # Database access layer + SQL files
│   │   ├── logic/            # Domain logic
│   │   ├── errors/           # Domain error definitions
│   │   ├── types/            # Shared types
│   │   ├── stitch.yaml       # Server stitch config
│   │   └── openapi/          # API route definitions
│   ├── ui/
│   │   ├── frontend.ts       # NoEgo client entry
│   │   ├── client.ts         # Forge client bootstrap
│   │   ├── index.html        # HTML shell template
│   │   ├── component/        # Svelte components
│   │   ├── lib/              # Frontend utilities (navigate, formatters)
│   │   ├── layout/           # Page layouts
│   │   ├── pages/            # Page components
│   │   ├── openapi/          # UI route definitions
│   │   └── stitch.yaml       # UI stitch config
│   ├── middleware/            # Shared middleware
│   └── jobs/                  # Background job tasks
├── migrations/               # Database migrations
├── test/                     # Integration & UI tests
├── noego.config.yml          # NoEgo configuration
├── proper.json               # Migration configuration
├── vite.config.js            # Vite + Svelte frontend build
├── tsconfig.json             # TypeScript configuration
└── package.json              # Dependencies and scripts

Architecture Flow

Here's how a request flows through NoEgo's layered architecture:

Server Flow (Dinner)

Frontend Flow (Forge)

Preferred: Direct Service Calls

Why direct calls? Loaders run on the server, so they can import and call Services directly via dependency injection—no HTTP round-trip needed.

The pattern: Frontend loaders call Services directly (no HTTP), which use Repositories to access the database. Data flows back to render the page. Controllers are only needed for external API access.

Key Directories Explained

src/server/ Server-Side Code

The src/server/ directory contains all your server-side TypeScript code:

server.ts: Entry that wires Dinner + controllers
container.ts: IoC container setup
controller/: HTTP request handlers that process API endpoints
services/: Business logic layer with IoC-managed services
repo/: Database access using SQLStack
logic/: Domain logic layer

src/ui/ Frontend Code

The src/ui/ directory contains all your Svelte components and UI configuration:

component/: Reusable Svelte components
lib/: Shared UI helpers (navigation, formatting)
layout/: Page layout wrappers
pages/: Route-specific page components
openapi/: YAML files defining page routes

Configuration Files

Your project includes several configuration files. You don't need to modify these to get started - the defaults work out of the box.

tsconfig.json - TypeScript settings with decorators enabled for dependency injection
proper.json - Database migration configuration
src/ui/stitch.yaml - Tells Forge where to find your UI OpenAPI routes
src/server/stitch.yaml - Tells Dinner where to find your API OpenAPI routes
noego.config.yml - Build and dev server settings
vite.config.js - Frontend build configuration (Vite + Svelte)

Open these files in your project to see the full configuration. We'll explore specific options as needed in later steps.

Environment Variables

NoEgo loads .env from the project root before starting the development server, and shell variables still take precedence.

Keep application secrets and connection strings in .env
Set one-off overrides in your shell before running npm run dev
Configure the default development port in noego.config.yml

.env

# Database connection
DATABASE_URL=./data/app.sqlite

# Application secrets
SESSION_SECRET=your-secret-key-here

Access these variables in your code using process.env:

src/index.ts

import express from "express";
import container from "./server/container";

export default function (_config: unknown) {
  const app = express();
  app.use(express.json());

  const dbUrl = process.env.DATABASE_URL;
  return app;
}

For a temporary port override, run PORT=3100 npm run dev. For the normal project default, use --port when creating the project or edit dev.port in noego.config.yml.

Important: Never commit your .env file to version control. Create a .env.example file with placeholder values for documentation.

Development vs Production Mode

NoEgo makes both development and deployment simple:

Development Mode (`npm run dev`)

Changes appear instantly—no manual refresh needed
Helpful error messages to fix issues fast

Production Mode (`npm run build`)

Optimized output in dist/
Run with node dist/no_ego.js

What's Next?

Now that you understand the project structure and configuration, let's create your first Svelte page and learn the basics of Forge routing.

Troubleshooting

Previous Step All Steps Next Step