@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/{get-started → guides/tutorials}/building-a-crud-api.md

@@ -2,11 +2,13 @@
 
 Build a complete, database-backed REST API for managing todos. This guide covers Models, DataSources, Repositories, and Controllers - the core building blocks of Ignis applications.
 
+**⏱️ Time to Complete:** ~45 minutes
+
 ## Prerequisites
 
-- ✅ Completed [Quickstart Guide](./quickstart.md)
+- ✅ Completed [Complete Installation](./complete-installation.md)
 - ✅ PostgreSQL installed and running
-- ✅ Database created (see [Prerequisites](./prerequisites.md))
+- ✅ Database created (see [Prerequisites](../get-started/setup.md))
 
 ## What You'll Build
 
@@ -28,63 +30,47 @@ Build a complete, database-backed REST API for managing todos. This guide covers
 Here's how a request flows through your application:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                     HTTP Request                             │
-│              GET /api/todos/:id                              │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-           ┌──────────────────┐
-           │ TodoController   │  ← Handles HTTP, validates input
-           │                  │
-           │ @get('/api/...')│
-           └─────────┬────────┘
-                     │
-                     │ calls repository.findById()
-                     ▼
-           ┌──────────────────┐
-           │ TodoRepository   │  ← Type-safe data access
-           │                  │
-           │ findById(id)     │
-           └─────────┬────────┘
-                     │
-                     │ uses dataSource.connector
-                     ▼
-           ┌──────────────────┐
-           │PostgresDataSource│  ← Database connection
-           │                  │
-           │ Drizzle ORM      │
-           └─────────┬────────┘
-                     │
-                     │ executes SQL query
-                     ▼
-           ┌──────────────────┐
-           │   PostgreSQL     │  ← Actual database
-           │                  │
-           │   Todo table     │
-           └─────────┬────────┘
-                     │
-                     │ returns data
-                     ▼
-           ┌──────────────────┐
-           │   JSON Response  │
-           │                  │
-           │ { id, title,..} │
-           └──────────────────┘
+HTTP Request (GET /api/todos/:id)
+            │
+            ▼
+   ┌─────────────────┐
+   │ TodoController  │  ← Handles HTTP, validates input
+   └────────┬────────┘
+            │ calls repository.findById()
+            ▼
+   ┌─────────────────┐
+   │ TodoRepository  │  ← Type-safe data access
+   └────────┬────────┘
+            │ uses dataSource.connector
+            ▼
+   ┌─────────────────┐
+   │PostgresDataSource│ ← Database connection (Drizzle ORM)
+   └────────┬────────┘
+            │ executes SQL query
+            ▼
+   ┌─────────────────┐
+   │   PostgreSQL    │  ← Actual database
+   └────────┬────────┘
+            │ returns data
+            ▼
+      JSON Response
 ```
 
 **Key Points:**
-1. **Controller** - Entry point for HTTP requests
-2. **Repository** - Abstracts database operations (you could swap PostgreSQL for MySQL without changing controller)
-3. **DataSource** - Manages connection to database
-4. **Model** - Defines what the data looks like
 
-This separation makes code:
-- **Testable** - Mock repository in tests
-- **Maintainable** - Clear responsibility for each layer
-- **Flexible** - Change database without touching business logic
+| Layer | Responsibility |
+|-------|----------------|
+| **Controller** | Entry point for HTTP requests |
+| **Repository** | Abstracts database operations (swap PostgreSQL for MySQL without changing controller) |
+| **DataSource** | Manages connection to database |
+| **Model** | Defines what the data looks like |
+
+**Benefits of this separation:**
+- **Testable** — Mock repository in tests
+- **Maintainable** — Clear responsibility for each layer
+- **Flexible** — Change database without touching business logic
 
-## Step 0: Install Database Dependencies
+## Step 1: Install Database Dependencies
 
 ```bash
 # Add database packages
@@ -94,7 +80,7 @@ bun add drizzle-orm drizzle-zod pg lodash
 bun add -d drizzle-kit @types/pg @types/lodash
 ```
 
-## Step 1: Define the Model
+## Step 2: Define the Model
 
 Models combine Drizzle ORM schemas with Entity classes to define your data structure.
 
@@ -142,36 +128,28 @@ export class Todo extends BaseEntity<typeof Todo.schema> {
 ```
 
 **Schema Enrichers:**
-- `generateIdColumnDefs()` - Adds `id` column (UUID primary key)
+- `generateIdColumnDefs()` - Adds `id` column (text with UUID default, or auto-incrementing number)
 - `generateTzColumnDefs()` - Adds `createdAt` and `modifiedAt` timestamps
 
-> **Deep Dive:** See [Models & Enrichers Reference](../references/base/models.md#schema-enrichers) for all available enrichers and options.
+> **Deep Dive:** See [Models & Enrichers Reference](/references/base/models#schema-enrichers) for all available enrichers and options.
 
-## Step 2: Configure Database Connection
+## Step 3: Configure Database Connection
 
 ### Understanding Environment Variables
 
-Before we connect to the database, let's understand **environment variables**.
+Environment variables store configuration outside code (in `.env` files). Benefits: security (no passwords in Git), flexibility (different values per environment).
 
-**What are they?**
-Environment variables are configuration values stored outside your code. Think of them as settings that can change without modifying your source code.
-
-**Why use them?**
 ```typescript
 // ❌ BAD: Hardcoded values
-const password = "secret123";  // Now it's in Git history forever!
+const password = "secret123";  // In Git history forever!
 
-// ✅ GOOD: Environment variable
-const password = process.env.DB_PASSWORD;  // Value comes from .env file
+// ✅ GOOD: Environment variable with APP_ENV_ prefix
+const password = process.env.APP_ENV_DB_PASSWORD;
+// or
+const password = Bun.env.APP_ENV_DB_PASSWORD;
 ```
 
-**Benefits:**
-1. **Security** - Never commit passwords to Git
-2. **Flexibility** - Different values for dev/staging/production
-3. **Team Collaboration** - Each developer has their own `.env` file
-
-**The `APP_ENV_` prefix:**
-Ignis uses `APP_ENV_` prefix for all its environment variables. This prevents conflicts with system variables (like `PATH`, `HOME`, etc.).
+Ignis uses `APP_ENV_` prefix to prevent conflicts with system variables.
 
 ### Create `.env` File
 
@@ -188,7 +166,7 @@ APP_ENV_POSTGRES_DATABASE=todo_db
 
 **Replace these values:**
 - `your_password_here` - Your PostgreSQL password (or leave blank if no password)
-- `todo_db` - The database you created in [Prerequisites](./prerequisites.md#database-setup)
+- `todo_db` - The database you created in [Prerequisites](../get-started/setup.md#database-setup)
 
 **Important:** Add `.env` to your `.gitignore`:
 ```bash
@@ -267,9 +245,17 @@ export class PostgresDataSource extends BaseDataSource<TNodePostgresConnector, I
 - Uses environment variables for connection config
 - Implements connection lifecycle methods (`connect()`, `disconnect()`)
 
-> **Deep Dive:** See [DataSources Reference](../references/base/datasources.md) for advanced configuration and multiple database support.
+> **Deep Dive:** See [DataSources Reference](/references/base/datasources) for advanced configuration and multiple database support.
+
+## Step 4: Create the Repository
+
+:::info What are Generic Types?
+Generic types in TypeScript are like placeholders that let you write reusable code that works with different types. The `<T>` syntax means "this class/function works with type T, which you'll specify later."
 
-## Step 3: Create the Repository
+Example: `DefaultCRUDRepository<typeof Todo.schema>` means "a repository that works specifically with the Todo schema type." This gives you type safety and autocomplete for your model's properties.
+
+[Learn more →](/guides/reference/glossary#generic-types)
+:::
 
 Repositories provide type-safe CRUD operations using `DefaultCRUDRepository`.
 
@@ -290,11 +276,33 @@ export class TodoRepository extends DefaultCRUDRepository<typeof Todo.schema> {
 ```
 
 **Available Methods:**
-`create()`, `find()`, `findOne()`, `findById()`, `updateById()`, `updateAll()`, `deleteById()`, `deleteAll()`, `count()`
 
-> **Deep Dive:** See [Repositories Reference](../references/base/repositories.md) for query options and advanced filtering.
+| Method | Description |
+|--------|-------------|
+| `create()` | Insert new record(s) |
+| `find()` | Query multiple records with filters |
+| `findOne()` | Get single record by filter |
+| `findById()` | Get record by ID |
+| `updateById()` | Update record by ID |
+| `updateAll()` | Update multiple records |
+| `deleteById()` | Delete record by ID |
+| `deleteAll()` | Delete multiple records |
+| `count()` | Count matching records |
+
+> **Deep Dive:** See [Repositories Reference](/references/base/repositories) for query options and advanced filtering.
+
+## Step 5: Create the Controller
+
+:::info What is Dependency Injection?
+Dependency Injection (DI) is a design pattern where objects receive their dependencies from outside rather than creating them internally. Instead of `new Repository()` inside a controller, you declare "I need a Repository" using `@inject`, and the framework provides it automatically.
+
+**Benefits:**
+- **Testable** — Replace real services with mocks in tests
+- **Flexible** — Swap implementations without changing code
+- **Maintainable** — Dependencies are explicit and centralized
 
-## Step 4: Create the Controller
+[Learn more →](/guides/core-concepts/dependency-injection)
+:::
 
 `ControllerFactory` generates a full CRUD controller with automatic validation and OpenAPI docs.
 
@@ -354,15 +362,15 @@ export class TodoController extends _Controller {
 | DELETE | `/todos/:id` | Delete todo by ID (deleteById) |
 | DELETE | `/todos` | Delete multiple todos by filter (deleteBy) |
 
-> **Deep Dive:** See [ControllerFactory Reference](../references/base/controllers.md#controllerfactory) for customization options.
+> **Deep Dive:** See [ControllerFactory Reference](/references/base/controllers#controllerfactory) for customization options.
 
-## Step 5: Register Components
+## Step 6: Register Components
 
 Update `src/application.ts` to register all components:
 
 ```typescript
 // src/application.ts
-import { BaseApplication, IApplicationConfigs, IApplicationInfo, ValueOrPromise } from '@venizia/ignis';
+import { BaseApplication, IApplicationConfigs, IApplicationInfo, SwaggerComponent, ValueOrPromise } from '@venizia/ignis';
 import { HelloController } from './controllers/hello.controller';
 import packageJson from '../package.json';
 
@@ -387,13 +395,16 @@ export class Application extends BaseApplication {
   setupMiddlewares(): ValueOrPromise<void> {}
 
   preConfigure(): ValueOrPromise<void> {
-    // 1. Register datasource
+    // 1. Register SwaggerComponent for API docs
+    this.component(SwaggerComponent);
+
+    // 2. Register datasource
     this.dataSource(PostgresDataSource);
 
-    // 2. Register repository
+    // 3. Register repository
     this.repository(TodoRepository);
 
-    // 3. Register controllers
+    // 4. Register controllers
     this.controller(HelloController);
     this.controller(TodoController);
   }
@@ -402,28 +413,16 @@ export class Application extends BaseApplication {
 }
 ```
 
-## Step 6: Run Database Migration
+## Step 7: Run Database Migration
 
 ### Understanding Database Migrations
 
-**The Problem:**
-Your database is currently empty. It has no `Todo` table. But your code expects one!
-
-```typescript
-// Your code says:
-todoTable = pgTable('Todo', { id: ..., title: ..., ... });
+Your code defines a `Todo` table, but PostgreSQL doesn't have it yet. A migration creates/modifies database tables - like "Git commits for your schema."
 
-// But PostgreSQL doesn't have a 'Todo' table yet!
-```
-
-**What is a Migration?**
-A migration is a script that creates or modifies database tables. Think of it as "Git commits for your database schema."
-
-**Example Migration:**
 ```sql
--- This is what Drizzle will generate and run for you
+-- Drizzle generates and runs this for you:
 CREATE TABLE "Todo" (
-  "id" UUID PRIMARY KEY,
+  "id" TEXT PRIMARY KEY,
   "title" TEXT NOT NULL,
   "description" TEXT,
   "is_completed" BOOLEAN DEFAULT false,
@@ -432,10 +431,7 @@ CREATE TABLE "Todo" (
 );
 ```
 
-**Why not create tables manually?**
-- **Team Collaboration** - Everyone runs the same migrations, databases stay in sync
-- **Version Control** - Schema changes are tracked in Git
-- **Rollback** - Can undo changes if something breaks
+Benefits: team sync, version control, rollback capability.
 
 ### Create Migration Config
 
@@ -460,9 +456,18 @@ export default defineConfig({
 });
 ```
 
-### Run the Migration
+### Add Migration Scripts
 
-Run the migration (using the script from [Quickstart](./quickstart.md#5-run-your-application)):
+Add these scripts to your `package.json`:
+
+```json
+"scripts": {
+  "migrate:dev": "NODE_ENV=development drizzle-kit migrate --config=src/migration.ts",
+  "generate-migration:dev": "NODE_ENV=development drizzle-kit generate --config=src/migration.ts"
+}
+```
+
+### Run the Migration
 
 ```bash
 bun run migrate:dev
@@ -491,7 +496,7 @@ psql -U postgres -d todo_db -c "\d Todo"
 
 You should see the `Todo` table structure with all your columns!
 
-## Step 7: Run and Test
+## Step 8: Run and Test
 
 Start your application:
 
@@ -523,7 +528,7 @@ curl -X DELETE http://localhost:3000/api/todos/{id}
 ```
 
 **View API Documentation:**
-Open `http://localhost:3000/docs` in your browser to see interactive Swagger UI.
+Open `http://localhost:3000/doc/explorer` to see interactive Swagger UI.
 
 🎉 **Congratulations!** You've built a complete CRUD API with:
 - ✅ Type-safe database operations
@@ -545,7 +550,6 @@ this.dataSource(PostgresDataSource);  // ← Make sure this is here!
 
 **Order matters:** DataSource must be registered before Repository.
 
----
 
 ### Error: "connection refused" or "ECONNREFUSED"
 
@@ -563,7 +567,6 @@ sudo service postgresql start      # Linux
 
 **Verify `.env` values match your PostgreSQL setup.**
 
----
 
 ### Error: "relation 'Todo' does not exist"
 
@@ -581,7 +584,6 @@ psql -U postgres -d todo_db -c "\dt"
 
 You should see `Todo` in the list.
 
----
 
 ### Error: 404 Not Found on `/api/todos`
 
@@ -598,7 +600,6 @@ path: { base: '/api', isStrict: true },  // All routes start with /api
 
 **Debug:** Set `debug.showRoutes: true` in appConfigs to see all registered routes on startup.
 
----
 
 ### Error: "Invalid JSON" when creating todo
 
@@ -612,7 +613,6 @@ curl -X POST http://localhost:3000/api/todos \
   -d '{"title":"Learn Ignis"}'
 ```
 
----
 
 ## Test Your Understanding: Build a Second Feature
 
@@ -624,18 +624,20 @@ Now that you've built the Todo API, try building a **User** feature on your own!
 - Use `ControllerFactory` for CRUD operations
 
 **Challenge checklist:**
-- [ ] Create `src/models/user.model.ts`
-- [ ] Create `src/repositories/user.repository.ts` (this auto-registers User with PostgresDataSource)
-- [ ] Create `src/controllers/user.controller.ts`
-- [ ] Register repository and controller in `application.ts`
-- [ ] Run migration: `bun run migrate:dev`
-- [ ] Test with curl
+
+| Step | Task |
+|:----:|------|
+| 1 | Create `src/models/user.model.ts` |
+| 2 | Create `src/repositories/user.repository.ts` (auto-registers User with PostgresDataSource) |
+| 3 | Create `src/controllers/user.controller.ts` |
+| 4 | Register repository and controller in `application.ts` |
+| 5 | Run migration: `bun run migrate:dev` |
+| 6 | Test with curl |
 
 **Hint:** Follow the exact same pattern as `Todo`. The only changes are the model name and fields!
 
-**Solution:** If you get stuck, check the [API Usage Examples](./best-practices/api-usage-examples.md) guide.
+**Solution:** If you get stuck, check the [API Usage Examples](/best-practices/api-usage-examples.md) guide.
 
----
 
 ## Next Steps
 
@@ -680,23 +682,23 @@ Register in `application.ts`:
 this.service(TodoService);
 ```
 
-> **Deep Dive:** See [Services Reference](./core-concepts/services.md) for best practices and advanced patterns.
+> **Deep Dive:** See [Services Reference](../core-concepts/services.md) for best practices and advanced patterns.
 
 ## Continue Your Journey
 
 You now have a fully functional CRUD API! Here's what to explore next:
 
 **Core Concepts:**
-1. [Application Architecture](./core-concepts/application.md) - Understand the framework structure
-2. [Dependency Injection](./core-concepts/dependency-injection.md) - Master DI patterns
-3. [Components](./core-concepts/components.md) - Build reusable modules
+1. [Application Architecture](../core-concepts/application/) - Understand the framework structure
+2. [Dependency Injection](../core-concepts/dependency-injection.md) - Master DI patterns
+3. [Components](../core-concepts/components.md) - Build reusable modules
 
 **Add Features:**
-1. [Authentication](../references/components/authentication.md) - Add JWT authentication
-2. [Custom Routes](./best-practices/api-usage-examples.md) - Beyond CRUD operations
-3. [Relationships](./core-concepts/persistent.md#querying-with-relations) - Link todos to users
+1. [Authentication](/references/components/authentication) - Add JWT authentication
+2. [Custom Routes](/best-practices/api-usage-examples.md) - Beyond CRUD operations
+3. [Relationships](../core-concepts/persistent/) - Link todos to users
 
 **Production:**
-1. [Deployment Strategies](./best-practices/deployment-strategies.md) - Deploy your API
-2. [Performance Optimization](./best-practices/performance-optimization.md) - Make it faster
-3. [Security Guidelines](./best-practices/security-guidelines.md) - Secure your API
+1. [Deployment Strategies](/best-practices/deployment-strategies.md) - Deploy your API
+2. [Performance Optimization](/best-practices/performance-optimization.md) - Make it faster
+3. [Security Guidelines](/best-practices/security-guidelines.md) - Secure your API