Skip to content

Frontend Project Structure

The Next.js frontend (apps/web/src) follows a feature-based folder structure, combined with Next.js App Router conventions.

Directory Layout

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
apps/web/
├── public/                 # Static assets (images, favicons, manifest)
└── src/
    ├── app/                # Next.js App Router (Pages, Layouts, API Routes)
    │   ├── (auth)/         # Route group for authentication pages
    │   ├── dashboard/      # The main authenticated application
    │   ├── layout.tsx      # Root layout
    │   └── page.tsx        # Landing page
    ├── components/         # React Components
    │   ├── common/         # Generic components (Buttons, Modals)
    │   ├── layout/         # Structural components (Sidebar, Topbar)
    │   ├── ui/             # shadcn/ui base components
    │   ├── finance/        # Feature-specific components
    │   ├── hr/             # Feature-specific components
    │   └── projects/       # Feature-specific components
    ├── contexts/           # React Context providers (AuthContext, ThemeContext)
    ├── hooks/              # Custom React Hooks
    ├── lib/                # Utility functions and API clients
    │   ├── auth.ts         # Authentication helpers
    │   ├── api-client.ts   # Axios/Fetch wrapper
    │   └── utils.ts        # General utilities (e.g., Tailwind merge)
    └── stores/             # Zustand global state stores

Component Organization

We strictly separate "UI Components" from "Feature Components".

1. UI Components (src/components/ui/)

These are "dumb", highly reusable components like Button, Input, Dialog, mostly generated by shadcn/ui. They have no business logic and do not fetch data.

2. Feature Components (src/components/[domain]/)

These are complex, domain-specific components like CreateInvoiceForm or KanbanBoard. - They may contain business logic. - They may fetch data or use custom hooks to interact with the backend API. - They compose multiple UI components together.

3. Layout Components (src/components/layout/)

Components that define the structure of the page, such as the global Sidebar, Topbar, or AppShell.

The lib Directory

The lib folder contains pure TypeScript logic: - api-client.ts: Configures the global fetch or axios instance, setting the base URL (NEXT_PUBLIC_API_URL) and automatically attaching authentication headers or handling token refreshes. - auth.ts: Wrapper functions around the Better Auth client SDK. - Domain API wrappers: e.g., projects.ts or finance.ts which contain functions like getProjects() or createInvoice() to keep data-fetching logic out of component files.