> For the complete documentation index, see [llms.txt](https://engineering-docs.innoxtech.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering-docs.innoxtech.co/onboarding.md).

# Onboarding

This document provides a comprehensive onboarding guide for frontend engineers working at Innox Technologies, including setup instructions, workflows, architecture overview and development standard.

## 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! 🚀