@venizia/ignis-docs 0.0.3 → 0.0.4-0

package/wiki/{get-started/quickstart.md → guides/tutorials/complete-installation.md}

@@ -1,8 +1,10 @@
-# Quickstart Guide
+# Complete Installation
 
 This guide walks you through creating a new web application with Ignis and setting up a professional development environment.
 
-> **Prerequisites:** Ensure you have [Bun installed and basic TypeScript knowledge](./prerequisites.md) before starting.
+**⏱️ Time to Complete:** ~20 minutes
+
+> **Prerequisites:** Ensure you have [Bun installed and basic TypeScript knowledge](../get-started/setup.md) before starting.
 
 ## 1. Initialize Your Project
 
@@ -30,7 +32,7 @@ bun add hono @hono/zod-openapi @scalar/hono-api-reference @venizia/ignis dotenv-
 ### Development Dependencies
 
 ```bash
-bun add -d typescript @types/bun @venizia/dev-configs tsc-alias tsconfig-paths
+bun add -d typescript @types/bun @venizia/dev-configs eslint prettier tsc-alias
 ```
 
 **What `@venizia/dev-configs` provides:**
@@ -108,38 +110,10 @@ export default eslintConfigs;
 > export default [...eslintConfigs, { rules: { 'no-console': 'warn' } }];
 > ```
 
-> **Deep Dive:** See [Code Style Standards](./best-practices/code-style-standards.md) for detailed configuration options.
-
-:::tip A Note on Setup for Express/Hono/Fastify Developers
-If you're coming from a minimal framework like Express, Hono, or Fastify, you might be thinking: "This is a lot of setup just to get started!"
-
-You're right—and it's intentional. Here's why:
-
-**In Express/Hono/Fastify, you might start with:**
-```javascript
-const app = require('express')();
-app.get('/', (req, res) => res.json({ hello: 'world' }));
-app.listen(3000);
-```
-
-That's 3 lines. Beautiful and fast.
+> **Deep Dive:** See [Code Style Standards](/best-practices/code-style-standards) for detailed configuration options.
 
-**The problem comes later:**
-- Where do you put database logic?
-- How do you organize routes when you have 50+ endpoints?
-- How do you share code between routes?
-- How do you validate requests?
-- How do you generate API docs?
-- How do you test business logic in isolation?
-
-`Ignis` answers these questions upfront with:
-- **Type Safety (`tsconfig.json`):** Catches errors before they reach production
-- **Consistent Formatting (`.prettierrc.mjs`):** No more debates about code style in PRs
-- **Code Quality (`eslint.config.mjs`):** Prevents common bugs and enforces best practices
-
-**The trade-off:** You write 50-100 lines of config once. In return, you get a scalable architecture that handles projects with 10, 100, or 1000+ endpoints without becoming spaghetti code.
-
-If you're building a quick prototype or tiny API (< 5 endpoints), stick with plain Hono. But if your API will grow or be maintained by a team, this setup pays for itself within a week.
+:::tip Coming from Express/Hono/Fastify?
+This setup might seem verbose compared to minimal frameworks. The trade-off: ~50 lines of config upfront gives you scalable architecture for 10-1000+ endpoints without spaghetti code. For quick prototypes (< 5 endpoints), use plain Hono instead.
 :::
 
 ## 4. Build Your First Application
@@ -147,24 +121,48 @@ If you're building a quick prototype or tiny API (< 5 endpoints), stick with pla
 ### Create Project Structure
 
 ```bash
-mkdir -p src/controllers
+mkdir -p src/{common,components,configurations,controllers,datasources,helpers,models/{entities,requests,responses},repositories,services,utilities}
 ```
 
 Your structure will look like:
 ```
 src/
-├── application.ts
-├── index.ts
-└── controllers/
-    └── hello.controller.ts
+├── index.ts                # Entry point
+├── application.ts          # Application class
+├── common/
+│   └── index.ts            # Shared constants, types, bindings
+├── components/
+│   └── index.ts            # Reusable modules (auth, swagger, etc.)
+├── configurations/
+│   └── index.ts            # App configuration files
+├── controllers/
+│   ├── index.ts            # Export all controllers
+│   └── hello.controller.ts
+├── datasources/
+│   └── index.ts            # Database connections
+├── helpers/
+│   └── index.ts            # Helper functions and classes
+├── models/
+│   ├── index.ts            # Export all models
+│   ├── entities/           # Drizzle schema definitions
+│   ├── requests/           # Request DTOs (Zod schemas)
+│   └── responses/          # Response DTOs (Zod schemas)
+├── repositories/
+│   └── index.ts            # Data access layer
+├── services/
+│   └── index.ts            # Business logic
+└── utilities/
+    └── index.ts            # Utility functions
 ```
 
+> **Note:** For this guide, we only use `controllers/`. Other folders will be used in the [CRUD Tutorial](./building-a-crud-api.md) when you add database support.
+
 ### Create Application Class
 
 Create `src/application.ts` - this is where you configure and register all your application resources:
 
 ```typescript
-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';
 
@@ -178,7 +176,15 @@ export const appConfigs: IApplicationConfigs = {
 export class Application extends BaseApplication {
   // Required: Tell the framework about your app (used for API docs)
   override getAppInfo(): ValueOrPromise<IApplicationInfo> {
+    // Option 1: Read from package.json (recommended for consistency)
     return packageJson;
+
+    // Option 2: Static app info (if package.json doesn't have correct fields)
+    // return {
+    //   name: 'my-app',
+    //   version: '1.0.0',
+    //   description: 'My Ignis application',
+    // };
   }
 
   // Hook 1: Configure static file serving (e.g., serve images from /public)
@@ -186,20 +192,31 @@ export class Application extends BaseApplication {
     // Example: this.static({ folderPath: './public' })
   }
 
-  // Hook 2: Add global middlewares (CORS, compression, etc.)
-  setupMiddlewares(): ValueOrPromise<void> {
-    // Example: this.server.use(cors())
+  // Hook 2: Add global middlewares (CORS, etc.)
+  override async setupMiddlewares(): Promise<void> {
+    const server = this.getServer();
+    const { cors } = await import('hono/cors');
+
+    server.use('*', cors({
+      origin: '*',
+      allowMethods: ['GET', 'HEAD', 'PUT', 'PATCH', 'POST', 'DELETE', 'OPTIONS'],
+      maxAge: 86_400,
+      credentials: true,
+    }));
   }
 
   // Hook 3: Register your resources (THIS IS THE MOST IMPORTANT ONE)
   preConfigure(): ValueOrPromise<void> {
+    // Register SwaggerComponent for API documentation at /doc/explorer
+    this.component(SwaggerComponent);
+
     // As your app grows, you'll add:
     // this.dataSource(PostgresDataSource);    // Database connection
     // this.repository(UserRepository);        // Data access layer
     // this.service(UserService);              // Business logic
     // this.component(AuthComponent);          // Auth setup
 
-    // For now, just register our controller
+    // Register our controller
     this.controller(HelloController);
   }
 
@@ -210,6 +227,17 @@ export class Application extends BaseApplication {
 }
 ```
 
+::: info IApplicationInfo
+**Required fields in `package.json`:**
+- `name` — App name (shown in API docs title)
+- `version` — App version (shown in API docs)
+- `description` — App description (shown in API docs)
+
+**No proper `package.json`?** Use static app info instead (see Option 2 in code above).
+
+**Recommendation:** Read from `package.json` for consistency between app metadata and API docs.
+:::
+
 **Key takeaway:** You'll mostly work in `preConfigure()` when building your app. The other hooks are there when you need them.
 
 **Application Lifecycle Hooks:**
@@ -221,7 +249,7 @@ export class Application extends BaseApplication {
 | `preConfigure()` | **Register resources** | **Main hook** - register controllers, services, etc. |
 | `postConfigure()` | Post-initialization | Optional - seed data, background jobs |
 
-> **Deep Dive:** See [Application Class Reference](./core-concepts/application.md) for detailed lifecycle documentation.
+> **Deep Dive:** See [Application Class Reference](../core-concepts/application/) for detailed lifecycle documentation.
 
 ### Create Controller
 
@@ -231,7 +259,7 @@ Create `src/controllers/hello.controller.ts` - controllers handle HTTP requests
 import {
   BaseController,
   controller,
-  get, // Import the 'get' decorator
+  api,
   HTTP,
   jsonContent,
 } from '@venizia/ignis';
@@ -248,9 +276,18 @@ export class HelloController extends BaseController {
     super({ scope: HelloController.name, path: BASE_PATH });
   }
 
-  // The @get decorator defines a GET route at /api/hello/
-  @get({
+  // Required: Override binding() to register routes or dependencies
+  override binding() {
+    // Option 1: Use bindRoute() or defineRoute() for programmatic route registration
+    // this.bindRoute({ method: 'get', path: '/programmatic', handler: this.myHandler });
+
+    // Option 2: Use @api decorator on methods (shown below) - recommended
+  }
+
+  // The @api decorator defines a route (prefer @api with method over @get/@post)
+  @api({
     configs: {
+      method: HTTP.Methods.GET,
       path: '/',
       // This 'responses' config does two things:
       // 1. Generates OpenAPI/Swagger documentation automatically
@@ -258,34 +295,31 @@ export class HelloController extends BaseController {
       responses: {
         [HTTP.ResultCodes.RS_2.Ok]: jsonContent({
           description: 'A simple hello message',
-          schema: z.object({ message: z.string() }), // Zod schema for validation
+          schema: z.object({ message: z.string() }),
         }),
       },
     },
   })
   sayHello(c: Context) {
-    // This looks just like Hono! Because it IS Hono under the hood.
     return c.json({ message: 'Hello, World!' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
-  // You can add more routes here:
-  // @post({ configs: { ... } })
-  // createSomething(c: Context) { ... }
-
-  // For authenticated endpoints, add 'authStrategies' to the configs:
-  // @get({ configs: { path: '/secure', authStrategies: [Authentication.STRATEGY_JWT] } })
-  // secureMethod(c: Context) { /* ... */ }
-
-  // For database CRUD operations, use ControllerFactory (covered in the CRUD tutorial)
+  // For authenticated endpoints, add 'authStrategies':
+  // @api({ configs: { method: HTTP.Methods.GET, path: '/secure', authStrategies: [Authentication.STRATEGY_JWT] } })
 }
 ```
 
-**Controller Decorators:**
-- `@controller` - Registers the class as a controller with a base path
-- `@get`, `@post`, `@put`, `@patch`, `@del` - Define HTTP endpoints
-- Zod schemas provide automatic validation and OpenAPI docs
+**Controller Patterns:**
+
+| Pattern | Description |
+|---------|-------------|
+| `@controller` | Registers the class as a controller with a base path |
+| `@api` | Defines a route with `method` specified (recommended) |
+| `@get`, `@post`, etc. | Shorthand decorators (also work) |
+| `binding()` | Required override — use `bindRoute()` or `defineRoute()` for programmatic routes |
+| Zod schemas | Provide automatic validation and OpenAPI docs |
 
-> **Deep Dive:** See [Controllers Reference](./core-concepts/controllers.md) for advanced routing patterns and validation.
+> **Deep Dive:** See [Controllers Reference](../core-concepts/controllers.md) for advanced routing patterns and validation.
 
 ### Create Entry Point
 
@@ -324,17 +358,15 @@ Add common application scripts to your `package.json`:
     "prettier:fix": "bun run prettier:cli --write",
     "eslint": "eslint --report-unused-disable-directives .",
     "build": "tsc -p tsconfig.json && tsc-alias -p tsconfig.json",
-    "compile:linux": "bun build --compile --minify --sourcemap --target=bun-linux-x64 ./src/index.ts --outfile ./dist/my_app",
     "clean": "sh ./scripts/clean.sh",
     "rebuild": "bun run clean && bun run build",
-    "migrate:dev": "NODE_ENV=development drizzle-kit push --config=src/migration.ts",
-    "generate-migration:dev": "NODE_ENV=development drizzle-kit generate --config=src/migration.ts",
-    "preserver:dev": "bun run rebuild",
     "server:dev": "NODE_ENV=development bun .",
     "server:prod": "NODE_ENV=production bun ."
 }
 ```
 
+> **Note:** Database migration scripts (`migrate:dev`, `generate-migration:dev`) will be added in the [CRUD Tutorial](./building-a-crud-api.md) when you set up Drizzle ORM.
+
 Create a cleanup script at `scripts/clean.sh`:
 
 ```bash
@@ -367,6 +399,10 @@ Response:
 {"message":"Hello, World!"}
 ```
 
+**View API Documentation:**
+
+Open `http://localhost:3000/doc/explorer` to see interactive Swagger UI with your endpoints.
+
 Congratulations! You have successfully created and configured your first application with the `Ignis` framework.
 
 ## Continue Your Journey
@@ -376,7 +412,7 @@ Congratulations! You have successfully created and configured your first applica
 **Next steps:**
 
 1. **[Building a CRUD API](./building-a-crud-api.md)** - Add database, create full REST API with CRUD operations
-2. **[Core Concepts](./core-concepts/application.md)** - Deep dive into application architecture
-3. **[Best Practices](./best-practices/architectural-patterns.md)** - Learn recommended patterns and practices
+2. **[Core Concepts](../core-concepts/application/)** - Deep dive into application architecture
+3. **[Best Practices](/best-practices/architectural-patterns)** - Learn recommended patterns and practices
 
-> **Deep Dive:** See [API Usage Examples](./best-practices/api-usage-examples.md) for more routing patterns and controller techniques.
+> **Deep Dive:** See [API Usage Examples](/best-practices/api-usage-examples) for more routing patterns and controller techniques.