@venizia/ignis-docs 0.0.1-1

package/wiki/get-started/best-practices/contribution-workflow.md

@@ -0,0 +1,145 @@
+# Contribution Workflow
+
+Guidelines for contributing to Ignis - help us maintain quality and streamline the process.
+
+## Git Branching Strategy
+
+```
+main (production)
+  ↑
+  │ merge only from develop
+  │
+develop (staging)
+  ↑
+  │ PRs target here
+  │
+feature/*, fix/*, docs/* (your work)
+```
+
+**Important:**
+- ✅ Create PRs to `develop` branch
+- ❌ Do NOT create PRs to `main` branch
+- `main` only accepts merges from `develop`
+- Releases are tagged in git (e.g., `v1.0.0`)
+
+## 1. Setup
+
+**Quick start:**
+```bash
+# 1. Fork the repository on GitHub
+
+# 2. Clone your fork
+git clone https://github.com/YOUR_USERNAME/ignis.git
+cd ignis
+
+# 3. Install dependencies
+bun install
+
+# 4. Add upstream remote
+git remote add upstream https://github.com/VENIZIA-AI/ignis.git
+```
+
+## 2. Development Workflow
+
+### Step 1: Create Branch
+
+```bash
+# Sync with upstream
+git fetch upstream
+git checkout main
+git merge upstream/main
+
+# Create feature branch
+git checkout -b feature/your-feature-name
+```
+
+**Branch naming:**
+| Type | Format | Example |
+|------|--------|---------|
+| Feature | `feature/description` | `feature/add-redis-cache` |
+| Bug fix | `fix/description` | `fix/auth-token-expiry` |
+| Docs | `docs/description` | `docs/update-quickstart` |
+| Chore | `chore/description` | `chore/upgrade-deps` |
+
+### Step 2: Make Changes
+
+**Checklist:**
+- ✅ Follow [Code Style Standards](./code-style-standards.md)
+- ✅ Follow [Architectural Patterns](./architectural-patterns.md)
+- ✅ Add tests for new features/fixes
+- ✅ Update docs in `packages/docs/wiki` if needed
+
+### Step 3: Commit
+
+Use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+# Examples
+git commit -m "feat: add Redis caching helper"
+git commit -m "fix: correct JWT token validation"
+git commit -m "docs: update controller examples"
+git commit -m "chore: upgrade Hono to v4.0"
+```
+
+**Commit types:**
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation only
+- `chore:` - Maintenance (deps, config)
+- `refactor:` - Code restructuring
+- `test:` - Adding tests
+
+### Step 4: Validate
+
+```bash
+# Lint and format
+bun run lint:fix
+
+# Build TypeScript
+bun run build
+
+# Run tests
+bun run test
+```
+
+## 3. Submit Pull Request
+
+```bash
+# Push your branch
+git push origin feature/your-feature-name
+```
+
+**PR Guidelines:**
+
+| Item | Description |
+|------|-------------|
+| **Title** | Use conventional commit format: `feat: add Redis caching` |
+| **Description** | Explain what and why (not just how) |
+| **Link issues** | Reference related issues: `Closes #123` |
+| **Screenshots** | Include for UI changes |
+| **Breaking changes** | Clearly mark and explain |
+
+**PR Checklist:**
+- ✅ All tests pass
+- ✅ Code is linted and formatted
+- ✅ Documentation updated
+- ✅ Commit messages follow conventions
+- ✅ Branch is up-to-date with `main`
+
+## 4. Review Process
+
+**What to expect:**
+1. Maintainer reviews your PR (usually within 2-3 days)
+2. Feedback or change requests may be provided
+3. Address feedback and push updates
+4. Once approved, maintainer merges to `main`
+
+**Responding to feedback:**
+```bash
+# Make requested changes
+git add .
+git commit -m "fix: address review feedback"
+git push origin feature/your-feature-name
+```
+
+**Thank you for contributing to Ignis! 🎉**

package/wiki/get-started/best-practices/deployment-strategies.md

@@ -0,0 +1,121 @@
+# Deployment Strategies
+
+Deploy your Ignis application reliably, securely, and efficiently.
+
+## 1. Building for Production
+
+Compile TypeScript to JavaScript before deploying:
+
+```bash
+bun run build
+```
+
+**What this does:**
+1. `tsc -p tsconfig.json` - Compile TypeScript → JavaScript
+2. `tsc-alias -p tsconfig.json` - Replace path aliases (`@/*`) with relative paths
+
+**Output:** `dist/` folder with production-ready JavaScript.
+
+## 2. Environment Configuration
+
+Use environment variables for all configuration - never hard-code.
+
+**Production Environment Variables:**
+| Variable | Value | Purpose |
+|----------|-------|---------|
+| `NODE_ENV` | `production` | Enables performance optimizations |
+| `APP_ENV_APPLICATION_SECRET` | Strong random string | Application secret |
+| `APP_ENV_JWT_SECRET` | Strong random string | JWT signing key |
+| `APP_ENV_POSTGRES_*` | Production DB credentials | Database connection |
+| `APP_ENV_SERVER_HOST` | `0.0.0.0` | Accept connections from any IP |
+| `APP_ENV_SERVER_PORT` | `3000` or cloud-assigned | Server port |
+
+**Where to store:**
+- **Docker:** Use environment variables in `docker-compose.yml` or secrets
+- **Kubernetes:** ConfigMaps and Secrets
+- **Cloud Platforms:** AWS Secrets Manager, Azure Key Vault, Google Secret Manager
+
+## 3. Deployment Methods
+
+### Docker Deployment (Recommended)
+
+**Dockerfile:**
+```dockerfile
+FROM node:20-slim
+
+WORKDIR /usr/src/app
+
+# Copy dependency files
+COPY package.json bun.lockb ./
+
+# Install production dependencies
+RUN bun install --production
+
+# Copy source code
+COPY . .
+
+# Build TypeScript
+RUN bun run build
+
+# Expose port
+EXPOSE 3000
+
+# Start server
+CMD [ "bun", "run", "server:prod" ]
+```
+
+**Build and deploy:**
+```bash
+# Build image
+docker build -t my-ignis-app .
+
+# Run container
+docker run -p 3000:3000 \
+  -e NODE_ENV=production \
+  -e APP_ENV_APPLICATION_SECRET=xxx \
+  my-ignis-app
+```
+
+### Bun Single Executable (Alternative)
+
+Compile your app into a single standalone binary:
+
+```bash
+bun build --compile --minify --target=bun-linux-x64 \
+  ./src/index.ts --outfile ./dist/my-app
+```
+
+**Pros:** No dependencies needed on server, simple deployment
+**Cons:** Platform-specific, newer technology (test thoroughly)
+
+**Deploy:**
+```bash
+# Copy executable and .env to server
+scp dist/my-app .env user@server:/app/
+
+# Run
+./my-app
+```
+
+## 4. Production Best Practices
+
+**Use a process manager:**
+- **PM2** - For Node.js/Bun processes
+- **systemd** - Linux service management
+- **Docker/Kubernetes** - Built-in orchestration
+
+**Example with PM2:**
+```bash
+pm2 start dist/index.js --name my-app -i max
+pm2 save
+pm2 startup
+```
+
+**Health checks:**
+Add health check endpoint for load balancers:
+```typescript
+// In application.ts
+this.component(HealthCheckComponent);
+```
+
+Access at `/health-check` for liveness/readiness probes.

package/wiki/get-started/best-practices/performance-optimization.md

@@ -0,0 +1,88 @@
+# Performance Optimization
+
+Optimize your Ignis application for speed and scalability.
+
+## 1. Measure Performance
+
+Identify bottlenecks before optimizing:
+
+```typescript
+import { executeWithPerformanceMeasure } from '@venizia/ignis';
+
+await executeWithPerformanceMeasure({
+  logger: this.logger,
+  scope: 'DataProcessing',
+  description: 'Process large dataset',
+  task: async () => {
+    await processLargeDataset();
+  },
+});
+```
+
+Logs execution time automatically.
+
+> **Deep Dive:** See [Performance Utility](../../references/utilities/performance.md) for advanced profiling.
+
+## 2. Offload CPU-Intensive Tasks
+
+Prevent blocking the event loop with Worker Threads:
+
+**Use Worker Threads for:**
+- Complex calculations or crypto operations
+- Large file/data processing
+- Any synchronous task > 5ms
+
+> **Deep Dive:** See [Worker Thread Helper](../../references/helpers/worker-thread.md) for implementation guide.
+
+## 3. Optimize Database Queries
+
+| Technique | Example | Impact |
+|-----------|---------|--------|
+| **Select specific fields** | `fields: { id: true, name: true }` | Reduce data transfer |
+| **Use indexes** | Create indexes on WHERE/JOIN columns | 10-100x faster queries |
+| **Paginate results** | `limit: 20, offset: 0` | Prevent memory overflow |
+| **Eager load relations** | `include: [{ relation: 'creator' }]` | Solve N+1 problem |
+
+**Example:**
+```typescript
+await userRepository.find({
+  filter: {
+    fields: { id: true, name: true, email: true },  // ✅ Specific fields
+    where: { status: 'ACTIVE' },
+    limit: 20,                                       // ✅ Pagination
+    include: [{ relation: 'profile' }],             // ✅ Eager load
+  },
+});
+```
+
+## 4. Implement Caching
+
+Reduce database load with caching:
+
+| Cache Type | Use Case | Implementation |
+|-----------|----------|----------------|
+| **Redis** | Distributed cache, session storage | [Redis Helper](../../references/helpers/redis.md) |
+| **In-Memory** | Single-process cache | `MemoryStorageHelper` |
+
+**Example:**
+```typescript
+// Cache expensive query results
+const cached = await redis.get('users:active');
+if (!cached) {
+  const users = await userRepository.find({ where: { active: true } });
+  await redis.set('users:active', users, 300); // 5 min TTL
+}
+```
+
+## 5. Production Settings
+
+| Setting | Value | Why |
+|---------|-------|-----|
+| `NODE_ENV` | `production` | Enables library optimizations |
+| Process Manager | PM2, systemd, Docker | Auto-restart, cluster mode |
+| Cluster Mode | CPU cores | Utilize all CPUs |
+
+**PM2 Cluster Mode:**
+```bash
+pm2 start dist/index.js -i max  # Use all CPU cores
+```

package/wiki/get-started/best-practices/security-guidelines.md

@@ -0,0 +1,97 @@
+# Security Guidelines
+
+Critical security practices to protect your Ignis application.
+
+## 1. Secret Management
+
+**Never hard-code secrets.** Use environment variables for all sensitive data.
+
+| Environment | Where to Store Secrets |
+|-------------|----------------------|
+| Development | `.env` file (add to `.gitignore`) |
+| Production | Cloud provider's secret manager (AWS Secrets Manager, Azure Key Vault, etc.) |
+
+**Example `.env`:**
+```bash
+APP_ENV_APPLICATION_SECRET=your_strong_random_secret_here
+APP_ENV_JWT_SECRET=another_strong_random_secret_here
+APP_ENV_POSTGRES_PASSWORD=database_password_here
+```
+
+**Generate strong secrets:**
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+```
+
+## 2. Input Validation
+
+**Always validate incoming data** with Zod schemas. Ignis automatically rejects invalid requests.
+
+```typescript
+import { z } from '@hono/zod-openapi';
+import { jsonContent, jsonResponse } from '@venizia/ignis';
+
+const CreateUserRoute = {
+  method: 'post',
+  path: '/users',
+  request: {
+    body: jsonContent({
+      schema: z.object({
+        email: z.string().email(),           // Valid email
+        age: z.number().int().min(18),       // Adult only
+        role: z.enum(['user', 'admin']),     // Whitelist
+      }),
+    }),
+  },
+  responses: jsonResponse({ /* ... */ }),
+} as const;
+```
+
+**Validation happens automatically** - invalid requests never reach your handler.
+
+## 3. Authentication & Authorization
+
+Protect sensitive endpoints with `AuthenticateComponent`.
+
+**Setup:**
+```typescript
+// application.ts
+this.component(AuthenticateComponent);
+```
+
+**Protect routes:**
+```typescript
+const SecureRoute = {
+  path: '/admin/users',
+  authStrategies: [Authentication.STRATEGY_JWT], // Requires JWT
+  // ...
+};
+```
+
+> **Deep Dive:** See [Authentication Component](../../references/components/authentication.md) for full setup guide.
+
+**Access user in protected routes:**
+```typescript
+const user = c.get(Authentication.CURRENT_USER) as IJWTTokenPayload;
+if (!user.roles.includes('admin')) {
+    throw new ApplicationError({ statusCode: 403, message: 'Forbidden' });
+}
+```
+
+## 4. Secure Dependencies
+
+Regularly audit and update dependencies:
+
+```bash
+# Check for vulnerabilities
+bun audit
+
+# Update dependencies
+bun update
+```
+
+**Critical packages to keep updated:**
+- `hono` - Web framework
+- `jose` - JWT handling
+- `drizzle-orm` - Database ORM
+- `@venizia/ignis` - Framework core

package/wiki/get-started/best-practices/troubleshooting-tips.md

@@ -0,0 +1,100 @@
+# Troubleshooting Tips
+
+Common issues and their solutions when building Ignis applications.
+
+## 1. Application Fails to Start
+
+| Symptom | Cause | Solution |
+|---------|-------|----------|
+| App exits immediately | Missing environment variables | Check `.env` file has all required vars (especially `APP_ENV_APPLICATION_SECRET`, `APP_ENV_JWT_SECRET`) |
+| Connection error on startup | Database unreachable | Verify `APP_ENV_POSTGRES_*` values and PostgreSQL is running |
+| `Error: listen EADDRINUSE` | Port already in use | Change `APP_ENV_SERVER_PORT` or stop conflicting process |
+
+**Quick fix:**
+```bash
+# Check if PostgreSQL is running
+psql -U postgres -c "SELECT 1;"
+
+# Find process using port 3000
+lsof -ti:3000 | xargs kill -9
+```
+
+## 2. API Endpoint Returns 404
+
+| Cause | Check | Fix |
+|-------|-------|-----|
+| Controller not registered | Missing in `application.ts` | Add `this.controller(MyController)` to `preConfigure()` |
+| Incorrect path | Typo in route path | Verify `@controller({ path })` and route path match URL |
+| Wrong base path | Missing `/api` prefix | Check `path.base` in application config |
+
+**Debug routes:**
+```typescript
+// In application.ts config
+export const appConfigs: IApplicationConfigs = {
+  debug: {
+    showRoutes: process.env.NODE_ENV !== 'production',
+  },
+};
+```
+
+This prints all registered routes on startup.
+
+## 3. Dependency Injection Fails (`Binding not found`)
+
+| Cause | Example Error | Fix |
+|-------|--------------|-----|
+| Resource not registered | `Binding 'services.MyService' not found` | Add `this.service(MyService)` to `preConfigure()` |
+| Wrong injection key | Key mismatch or typo | Use `BindingKeys.build()` helper |
+| Wrong namespace | Using `repository` instead of `service` | Check correct namespace in `@inject` |
+
+**Debug bindings:**
+```typescript
+// In postConfigure() method
+async postConfigure(): Promise<void> {
+  this.logger.info('Available bindings: %s',
+    Array.from(this.bindings.keys())
+  );
+}
+```
+
+## 4. Authentication Fails (401 Unauthorized)
+
+| Symptom | Cause | Solution |
+|---------|-------|----------|
+| `401 Unauthorized` on protected route | Missing Authorization header | Add `Authorization: Bearer <token>` header |
+| Token expired | JWT past expiration | Request new token from login endpoint |
+| Invalid signature | Wrong `JWT_SECRET` | Ensure `APP_ENV_JWT_SECRET` matches across services |
+| Malformed header | Missing "Bearer " prefix | Format: `Bearer eyJhbGc...` |
+
+**Test with curl:**
+```bash
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  http://localhost:3000/api/protected-route
+```
+
+## 5. General Debugging Tips
+
+**Enable detailed logging:**
+```typescript
+// Increase log verbosity
+LoggerFactory.setLevel('debug');
+```
+
+**Common debugging commands:**
+```bash
+# View application logs
+tail -f logs/app.log
+
+# Check TypeScript compilation errors
+bun run build
+
+# Validate environment variables
+cat .env | grep APP_ENV
+```
+
+**Useful debugging patterns:**
+- Add `console.log()` in route handlers to trace execution
+- Use `try-catch` blocks to catch and log errors
+- Check database queries with Drizzle's logging: `{ logger: true }`
+
+> **Deep Dive:** See [Logger Helper](../../references/helpers/logger.md) for advanced logging configuration.