# Onboarding

## Engineering Onboarding Guide

This guide will help you get up and running with any of innox project.

### Table of Contents

* Prerequisites
* Quick Start
* Development Workflow
* Project Structure
* Key Technologies
* Testing
* Common Tasks
* Resources

### Prerequisites

Before you begin, ensure you have:

* **Node.js**: v18.17.0 or higher (v20+ recommended)
* **npm**: v9.0.0 or higher
* **Git**: Latest version
* **Code Editor**: VS Code with recommended extensions

#### VS Code Extensions (Recommended)

* ESLint
* Prettier
* TypeScript and JavaScript Language Features
* Auto Import
* Path Intellisense

### Quick Start

#### 1. Clone the Repository

```bash
git clone <repository-url>
cd lodgr-admin
```

#### 2. Install Dependencies

```bash
npm install
```

#### 3. Set Up Environment Variables

Create a `.env.local` file in the root directory:

```env
# NextAuth Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here

# Generate a secret with: openssl rand -base64 32
```

#### 4. Run Development Server

```bash
npm run dev
```

The application will be available at <http://localhost:3000>

### 5. Development Workflow

#### Branch Strategy

* `main` - Production-ready code
* `staging` - For QA and External testing
* `develop` - Integration branch for features
* `feature/*` - Feature branches
* `bugfix/*` - Bug fix branches

#### Commit Convention

We follow conventional commits:

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

**Types:**

* `feat` - New feature
* `fix` - Bug fix
* `docs` - Documentation changes
* `style` - Code style changes (formatting, etc.)
* `refactor` - Code refactoring
* `test` - Adding or updating tests
* `chore` - Maintenance tasks

**Examples:**

```bash
feat(auth): add OAuth provider support
fix(users): resolve pagination bug
docs(readme): update setup instructions
```

#### Code Review Process

1. Create a feature branch from `develop`
2. Implement your changes
3. Run tests and linting
4. Create a pull request
5. Request review from team members
6. Address feedback
7. Merge after approval

#### Running Tests

```bash
# Run all tests
npm test

# Run tests in watch mode
npm test:watch

# Run tests with coverage
npm test:coverage
```

#### Building for Production

```bash
# Create production build
npm run build

# Preview production build
npm run start
```

### Key Technologies

#### Next.js 15+ with App Router

* **Server Components**: Default for all pages
* **Client Components**: Use `"use client"` directive for interactivity
* **Server Actions**: Use `"use server"` for data mutations
* **File-based Routing**: Routes defined by file structure

**Important Rules:**

* Keep components as Server Components by default
* Only use Client Components when necessary (forms, interactive UI)
* Use Server Actions for all data mutations (no client-side fetch)
* Never use `useEffect` for data fetching

#### Chakra UI v3

**Note:** Chakra UI v3 has a completely different API from v2.

**Key Changes from v2:**

* `Provider` renamed to `ChakraProvider`
* Use `defaultSystem` instead of `system()`
* Many components removed (Avatar, Switch, Table)
* Props renamed (e.g., `bgPalette` → `colorPalette`)

**Theme Usage:**

```typescript
// Use semantic tokens for consistency
<Box bg="bg.subtle">        // Background colors
<Text color="text.primary"> // Text colors
<Button colorPalette="primary"> // Interactive elements
```

#### NextAuth v5 Beta

**Configuration:**

* Credentials provider with bcrypt password hashing
* JWT strategy for sessions
* Role-based access control

**Usage:**

```typescript
import { auth } from "@/lib/auth/config";
import { signOut } from "next-auth/react";

// Server-side
const session = await auth();

// Client-side
const { data: session } = useSession();
```

#### TypeScript

**Type Definitions:** Located in `src/types/index.ts`

**ActionResult Pattern:**

```typescript
type ActionResult<T> =
  | { success: true; data: T }
  | { success: false; error: string };

// Usage in Server Actions
export async function getUsers(): Promise<ActionResult<User[]>> {
  try {
    const users = await fetchUsers();
    return { success: true, data: users };
  } catch (error) {
    return { success: false, error: "Failed to fetch users" };
  }
}
```

### Testing

#### Test Structure

```
src/
├── __tests__/
│   ├── unit/      # Unit tests
│   ├── integration/ # Integration tests
│   └── e2e/       # End-to-end tests
```

#### Writing Tests

**Server Actions:**

```typescript
import { getUsers } from '@/app/actions/users';

describe('getUsers', () => {
  it('should return users for admin', async () => {
    // Mock auth
    // Test function
    // Assert results
  });
});
```

#### Test Commands

```bash
npm test              # Run all tests
npm test:watch        # Watch mode
npm test:coverage     # Generate coverage report
```

### Common Tasks

#### Adding a New Page

1. Create a new directory in `src/app/`
2. Add `page.tsx` file
3. Export a default Server Component

Example:

```typescript
// src/app/new-page/page.tsx
import { auth } from "@/lib/auth/config";

export default async function NewPage() {
  const session = await auth();

  if (!session) {
    redirect("/login");
  }

  return (
    <div>
      <h1>New Page</h1>
    </div>
  );
}
```

#### Creating a Server Action

1. Create file in `src/app/actions/`
2. Add `"use server"` directive
3. Export async function
4. Return `ActionResult<T>` type

Example:

```typescript
// src/app/actions/example.ts
"use server";

import { auth } from "@/lib/auth/config";
import type { ActionResult } from "@/types";

export async function doSomething(): Promise<ActionResult<void>> {
  const session = await auth();

  if (!session?.user) {
    return { success: false, error: "Unauthorized" };
  }

  try {
    // Perform action
    return { success: true, data: undefined };
  } catch (error) {
    return { success: false, error: "Something went wrong" };
  }
}
```

#### Adding a UI Component

1. Create component in `src/components/ui/`
2. Export as named export
3. Use Chakra UI v3 components
4. Add TypeScript props

Example:

```typescript
// src/components/ui/card.tsx
interface CardProps {
  children: React.ReactNode;
  title?: string;
}

export function Card({ children, title }: CardProps) {
  return (
    <Box p={4} borderWidth="1px" borderRadius="md">
      {title && <Text fontSize="lg" fontWeight="bold">{title}</Text>}
      {children}
    </Box>
  );
}
```

### Resources

#### Documentation

* [Next.js Documentation](https://nextjs.org/docs)
* [Chakra UI v3 Docs](https://v3.chakra-ui.com/)
* [NextAuth.js v5 Docs](https://authjs.dev/)
* [TypeScript Handbook](https://www.typescriptlang.org/docs/)

#### Internal Documentation

* ARCHITECTURE.md - System design and architecture
* CODE\_PATTERNS.md - Code conventions and patterns
* TROUBLESHOOTING.md - Common issues and solutions

#### Getting Help

1. Check existing documentation
2. Search existing GitHub issues
3. Ask in team chat/Slack
4. Create a new issue with detailed description

### Next Steps

1. Complete the Quick Start setup
2. Read ARCHITECTURE.md to understand the system design
3. Review CODE\_PATTERNS.md for coding conventions
4. Explore the codebase using the project structure guide
5. Start with a small task or bug fix

Welcome aboard! 🚀


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://engineering-docs.innoxtech.co/onboarding.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.