> ## Documentation Index
> Fetch the complete documentation index at: https://zarna.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Project Structure

> Directory organization and file conventions for the Zarna frontend

## Directory Overview

The Zarna frontend follows a structured, modular organization:

```
zarna-frontend/
├── src/                      # Source code
│   ├── components/           # React components
│   │   ├── ui/              # shadcn/ui components (auto-generated)
│   │   ├── layout/          # Layout components
│   │   ├── features/        # Feature-specific components
│   │   └── generated/       # Generated components
│   │
│   ├── context/             # React Context providers
│   │   ├── AuthContext.tsx
│   │   └── CompanyContext.tsx
│   │
│   ├── hooks/               # Custom React hooks
│   │   ├── use-mobile.ts
│   │   ├── use-toast.ts
│   │   └── use-auth.ts
│   │
│   ├── lib/                 # Utility functions
│   │   └── utils.ts
│   │
│   ├── services/            # API integration
│   │   └── api.ts
│   │
│   ├── utils/               # Helper functions
│   │
│   ├── App.tsx              # Main application component
│   ├── main.tsx             # Application entry point
│   └── index.css            # Global styles
│
├── public/                   # Static assets
│   ├── images/
│   ├── fonts/
│   └── icons/
│
├── components.json           # shadcn/ui configuration
├── tsconfig.json            # TypeScript configuration
├── vite.config.ts           # Vite configuration
├── tailwind.config.js       # Tailwind CSS configuration
├── postcss.config.mjs       # PostCSS configuration
├── package.json             # Dependencies and scripts
├── .eslintrc.json          # ESLint configuration
├── .prettierrc             # Prettier configuration
└── README.md               # Project documentation
```

## Directory Guidelines

### `src/components/`

Component organization by purpose:

#### `ui/` - shadcn/ui Components

**🚨 DO NOT MANUALLY EDIT** - Generated by shadcn CLI

```
components/ui/
├── button.tsx               # Button component
├── card.tsx                 # Card component
├── dialog.tsx               # Dialog/modal component
├── dropdown-menu.tsx        # Dropdown menu component
├── form.tsx                 # Form component
├── input.tsx                # Input component
├── select.tsx               # Select component
├── table.tsx                # Table component
├── toast.tsx                # Toast notification component
└── ...                      # 40+ more components
```

**Adding components**:

```bash theme={null}
npx shadcn@latest add button
npx shadcn@latest add dialog
```

#### `layout/` - Layout Components

Reusable layout components:

```
components/layout/
├── Layout.tsx               # Main layout wrapper
├── Header.tsx               # Application header
├── Sidebar.tsx              # Navigation sidebar
├── Footer.tsx               # Application footer
└── Container.tsx            # Content container
```

#### `features/` - Feature Components

Domain-specific components organized by feature:

```
components/features/
├── auth/
│   ├── LoginForm.tsx
│   ├── RegisterForm.tsx
│   └── ResetPasswordForm.tsx
│
├── companies/
│   ├── CompanyCard.tsx
│   ├── CompanyList.tsx
│   ├── CompanyForm.tsx
│   └── CompanyDetails.tsx
│
├── deals/
│   ├── DealPipeline.tsx
│   ├── DealCard.tsx
│   └── DealForm.tsx
│
└── files/
    ├── FileUploader.tsx
    ├── FileViewer.tsx
    └── PDFViewer.tsx
```

### `src/context/`

React Context for global state:

```typescript theme={null}
// AuthContext.tsx
import { createContext, useContext, useState } from 'react'

interface AuthContextType {
  user: User | null
  login: (credentials: Credentials) => Promise<void>
  logout: () => void
  isAuthenticated: boolean
}

const AuthContext = createContext<AuthContextType | undefined>(undefined)

export function AuthProvider({ children }) {
  // Context implementation
}

export function useAuth() {
  const context = useContext(AuthContext)
  if (!context) throw new Error('useAuth must be used within AuthProvider')
  return context
}
```

**Current Contexts**:

* `AuthContext` - Authentication state
* `CompanyContext` - Current company selection

### `src/hooks/`

Custom React hooks for reusable logic:

```
hooks/
├── use-auth.ts              # Authentication hook
├── use-mobile.ts            # Mobile detection hook
├── use-toast.ts             # Toast notifications hook
├── use-debounce.ts          # Debounce hook
├── use-local-storage.ts     # LocalStorage hook
└── use-api.ts               # API call hook
```

**Example hook**:

```typescript theme={null}
// hooks/use-mobile.ts
import { useEffect, useState } from "react"

const MOBILE_BREAKPOINT = 768

export function useMobile() {
  const [isMobile, setIsMobile] = useState<boolean>(false)

  useEffect(() => {
    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
    const onChange = () => setIsMobile(mql.matches)

    mql.addEventListener("change", onChange)
    setIsMobile(mql.matches)

    return () => mql.removeEventListener("change", onChange)
  }, [])

  return isMobile
}
```

### `src/lib/`

Pure utility functions (no React dependencies):

```typescript theme={null}
// lib/utils.ts
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

export function formatCurrency(amount: number): string {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD'
  }).format(amount)
}

export function truncate(str: string, length: number): string {
  return str.length > length ? str.substring(0, length) + '...' : str
}
```

### `src/services/`

API integration and external service calls:

```typescript theme={null}
// services/api.ts
const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:8000'

export async function fetchCompanies() {
  const response = await fetch(`${API_BASE_URL}/api/companies`)
  return response.json()
}

export async function createCompany(data: CompanyCreate) {
  const response = await fetch(`${API_BASE_URL}/api/companies`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  })
  return response.json()
}
```

### `public/`

Static assets served as-is:

```
public/
├── images/
│   ├── logo.svg
│   ├── hero.png
│   └── avatars/
│
├── fonts/
│   └── custom-font.woff2
│
└── icons/
    ├── favicon.ico
    └── manifest.json
```

**Usage**:

```tsx theme={null}
<img src="/images/logo.svg" alt="Logo" />
```

## File Naming Conventions

### Components

* **PascalCase**: `ComponentName.tsx`
* **Examples**: `Button.tsx`, `UserProfile.tsx`, `DealPipeline.tsx`

### Hooks

* **kebab-case**: `use-hook-name.ts`
* **Examples**: `use-auth.ts`, `use-mobile.ts`, `use-debounce.ts`

### Utilities

* **kebab-case**: `util-name.ts`
* **Examples**: `format-date.ts`, `api-client.ts`, `validation.ts`

### Context

* **PascalCase**: `ContextName.tsx`
* **Examples**: `AuthContext.tsx`, `ThemeContext.tsx`

### Types

* **PascalCase**: `TypeName.ts` or inline in component files
* **Examples**: `types.ts`, `api-types.ts`

## Import Organization

Order imports for consistency:

```typescript theme={null}
// 1. External dependencies
import * as React from "react"
import { useState, useEffect } from "react"
import { useNavigate } from "react-router-dom"

// 2. Internal components
import { Button } from "@/components/ui/button"
import { Card } from "@/components/ui/card"

// 3. Hooks
import { useAuth } from "@/hooks/use-auth"
import { useMobile } from "@/hooks/use-mobile"

// 4. Utils
import { cn } from "@/lib/utils"
import { formatDate } from "@/utils/format"

// 5. Types
import type { User, Company } from "@/types"

// 6. Styles (if any)
import "./styles.css"
```

## Path Aliases

Configured in `tsconfig.json`:

```json theme={null}
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

**Usage**:

```typescript theme={null}
// ✅ Good - using alias
import { Button } from "@/components/ui/button"
import { useAuth } from "@/hooks/use-auth"

// ❌ Bad - relative imports
import { Button } from "../../../components/ui/button"
```

## Configuration Files

### `tsconfig.json`

TypeScript configuration with strict mode:

```json theme={null}
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

### `vite.config.ts`

Vite build configuration:

```typescript theme={null}
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  },
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8000',
        changeOrigin: true
      }
    }
  }
})
```

### `tailwind.config.js`

Tailwind CSS configuration:

```javascript theme={null}
/** @type {import('tailwindcss').Config} */
export default {
  darkMode: ["class"],
  content: [
    "./index.html",
    "./src/**/*.{ts,tsx}"
  ],
  theme: {
    extend: {
      colors: {
        border: "hsl(var(--border))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        // ... theme colors
      }
    }
  },
  plugins: [require("tailwindcss-animate")]
}
```

### `components.json`

shadcn/ui configuration:

```json theme={null}
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}
```

## Best Practices

### Component Organization

<AccordionGroup>
  <Accordion title="Keep components focused">
    Each component should have a single responsibility. If a component does too much, split it.
  </Accordion>

  <Accordion title="Co-locate related files">
    Keep component-specific styles, tests, and utilities near the component.
  </Accordion>

  <Accordion title="Use feature folders">
    Group related components by feature rather than type.
  </Accordion>

  <Accordion title="Extract reusable logic">
    Move common logic to custom hooks or utility functions.
  </Accordion>
</AccordionGroup>

### Naming Conventions

* **Be descriptive**: `UserProfileCard` > `Card`
* **Be consistent**: Always use PascalCase for components
* **Prefix hooks**: Always start with `use` (e.g., `useAuth`)
* **Suffix contexts**: End with `Context` (e.g., `AuthContext`)

## Next Steps

<CardGroup cols={2}>
  <Card title="Components Guide" icon="puzzle-piece" href="/frontend/components">
    Learn component patterns and architecture
  </Card>

  <Card title="Theme System" icon="palette" href="/frontend/theme-system">
    Understand the color system and theming
  </Card>

  <Card title="Best Practices" icon="star" href="/frontend/best-practices">
    Follow coding standards
  </Card>

  <Card title="Tech Stack" icon="layer-group" href="/frontend/tech-stack">
    Explore all technologies
  </Card>
</CardGroup>