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

git clone <repository-url>
cd lodgr-admin

2. Install Dependencies

npm install

3. Set Up Environment Variables

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

# 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

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:

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

# Run all tests
npm test

# Run tests in watch mode
npm test:watch

# Run tests with coverage
npm test:coverage

Building for Production

# 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:

// 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:

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:

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:

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

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

Test Commands

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:

// 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:

// 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:

// 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

• Chakra UI v3 Docs

• NextAuth.js v5 Docs

• TypeScript Handbook

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