---
title: "Project Architecture"
description: "Understand the architecture and codebase structure of Reactive Resume"
---

This guide provides a comprehensive overview of Reactive Resume's architecture and codebase structure, helping you understand how different parts of the application work together.

---

## Tech Stack Overview

Reactive Resume is built with a modern, type-safe stack:

<CardGroup cols={2}>
  <Card title="Frontend" icon="browser">
    - **React 19** with TanStack Start - **TypeScript** for type safety - **Tailwind CSS** for styling - **Radix UI**
    for accessible components
  </Card>
  <Card title="Backend" icon="server">
    - **ORPC** for type-safe RPC - **Drizzle ORM** with PostgreSQL - **Better Auth** for authentication - **Sharp** for
    image processing
  </Card>
</CardGroup>

---

## Application Architecture

```mermaid
flowchart TD
  %% Client Side
  subgraph Client ["Client"]
    Router["TanStack Router"]
    Query["TanStack Query"]
    ORPCClient["oRPC Client"]
  end

  %% Server Side
  subgraph Server ["Server"]
    ORPCRouter["oRPC Router"]
    Auth["Better Auth"]
    Services["Services Layer"]
    Drizzle["Drizzle ORM"]
  end

  Database["PostgreSQL"]
  Storage["File System OR S3-Compatible Storage"]
  Printer["Printer (Browserless/Chromium)"]

  Router --> ORPCClient
  Query --> ORPCClient
  ORPCClient -- calls --> ORPCRouter
  ORPCRouter --> Services
  Auth --> Services
  Services --> Drizzle
  Drizzle --> Database
  Services --> Storage
  Services --> Printer
```

**Diagram:** This flow shows data and control flow between the main architectural layers of Reactive Resume.

---

## Directory Structure

### Root Level

| Directory     | Purpose                             |
| ------------- | ----------------------------------- |
| `src/`        | Main application source code        |
| `public/`     | Static assets served directly       |
| `locales/`    | Translation files (.po format)      |
| `migrations/` | Database migration files            |
| `docs/`       | Mintlify documentation              |
| `data/`       | Local data storage (fonts, uploads) |
| `scripts/`    | Utility scripts                     |

### Source Code (`src/`)

<AccordionGroup>
	<Accordion title="components/" icon="cube">
		Reusable React components organized by category: - **`ui/`** — Base UI components (Button, Card, Dialog, etc.) -
		**`resume/`** — Resume-specific components (sections, templates) - **`input/`** — Form input components
		(ColorPicker, RichInput) - **`layout/`** — Layout components (Sidebar, LoadingScreen) - **`animation/`** — Animation
		components (Spotlight, TextMask) - **`theme/`** — Theme management components - **`typography/`** — Font management
		components
	</Accordion>

    <Accordion title="routes/" icon="route">
    	File-based routing using TanStack Router: - **`__root.tsx`** — Root layout with providers - **`_home/`** — Public
    	home page routes - **`auth/`** — Authentication routes (login, register, etc.) - **`dashboard/`** — User dashboard
    	routes - **`builder/`** — Resume builder routes (the main editor) - **`printer/`** — PDF printing route - **`api/`**
    	— API routes
    </Accordion>

    <Accordion title="integrations/" icon="plug">
    	Third-party service integrations: - **`auth/`** — Better Auth client configuration - **`drizzle/`** — Database
    	schema and utilities - **`orpc/`** — API router, client, and services - **`ai/`** — AI service integrations -
    	**`import/`** — Resume import utilities
    </Accordion>

    <Accordion title="dialogs/" icon="window-maximize">
    	Modal dialog components: - **`auth/`** — Authentication dialogs - **`resume/`** — Resume management dialogs -
    	**`api-key/`** — API key management dialogs - **`manager.tsx`** — Dialog manager component - **`store.ts`** — Dialog
    	state management (Zustand)
    </Accordion>

    <Accordion title="schema/" icon="file-code">
    	Zod schemas for validation: - **`resume/`** — Resume data schemas - **`icons.ts`** — Icon definitions -
    	**`templates.ts`** — Template definitions
    </Accordion>

    <Accordion title="hooks/" icon="hook">
    	Custom React hooks: - `use-confirm.tsx` — Confirmation dialog hook - `use-prompt.tsx` — Prompt dialog hook -
    	`use-mobile.tsx` — Mobile detection hook - `use-safe-context.tsx` — Safe context consumption
    </Accordion>

    <Accordion title="utils/" icon="wrench">
    	Utility functions: - `env.ts` — Environment variable validation - `locale.ts` — Locale utilities - `theme.ts` —
    	Theme utilities - `string.ts` — String manipulation - `file.ts` — File handling utilities
    </Accordion>

</AccordionGroup>

---

## Key Concepts

### File-Based Routing

Routes are automatically generated from the file structure in `src/routes/`. TanStack Router conventions:

| Pattern      | Description           | Example              |
| ------------ | --------------------- | -------------------- |
| `index.tsx`  | Index route           | `/dashboard`         |
| `$param.tsx` | Dynamic parameter     | `/builder/$resumeId` |
| `_layout/`   | Layout group (prefix) | `_home/`             |
| `__root.tsx` | Root layout           | Wraps all routes     |

<Warning>Never edit `src/routeTree.gen.ts` manually — it's auto-generated when you run the dev server.</Warning>

### API Layer (ORPC)

ORPC provides end-to-end type safety for API calls:

```
src/integrations/orpc/
├── client.ts         # Client-side ORPC setup
├── router/           # API route definitions
│   ├── auth.ts      # Authentication endpoints
│   ├── resume.ts    # Resume CRUD operations
│   └── storage.ts   # File storage operations
├── services/         # Business logic layer
└── helpers/          # Utility functions
```

**Using the API client:**

```tsx
import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/integrations/orpc/client";

// Type-safe API calls with TanStack Query
const { data } = useQuery(orpc.resume.findMany.queryOptions());
```

### State Management

Reactive Resume uses a hybrid approach:

| Type         | Tool            | Use Case                       |
| ------------ | --------------- | ------------------------------ |
| Server State | TanStack Query  | API data, caching, sync        |
| Client State | Zustand         | UI state, dialogs, preferences |
| Form State   | React Hook Form | Form inputs and validation     |

### Database Schema

The database schema is defined using Drizzle ORM in `src/integrations/drizzle/schema.ts`:

```tsx
import { pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";

export const resume = pgTable("resume", {
  id: uuid("id").primaryKey().defaultRandom(),
  title: text("title").notNull(),
  slug: text("slug").notNull(),
  // ... more fields
});
```

---

## Common Development Patterns

### Adding a New Component

1. Create the component in the appropriate `src/components/` subdirectory
2. Export it from the directory's index file (if applicable)
3. Use TypeScript props interfaces for type safety
4. Follow existing patterns for consistency

```tsx
// src/components/ui/my-component.tsx
import { cn } from "@/utils/style";

interface MyComponentProps {
  title: string;
  className?: string;
}

export const MyComponent = ({ title, className }: MyComponentProps) => {
  return <div className={cn("p-4", className)}>{title}</div>;
};
```

### Adding a New Route

1. Create a new file in `src/routes/` following TanStack Router conventions
2. The route tree auto-generates when you save
3. Use `createFileRoute` for type-safe routes

```tsx
// src/routes/my-page.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/my-page")({
  component: MyPage,
});

function MyPage() {
  return <div>My Page Content</div>;
}
```

### Adding an API Endpoint

1. Add the route handler in `src/integrations/orpc/router/`
2. Create service functions in `src/integrations/orpc/services/` if needed
3. The endpoint is automatically typed on the client

```tsx
// In router file
import { z } from "zod";
import { publicProcedure, router } from "../server";

export const myRouter = router({
  hello: publicProcedure.input(z.object({ name: z.string() })).handler(async ({ input }) => {
    return { message: `Hello, ${input.name}!` };
  }),
});
```

### Adding Translations

1. Wrap text with `t` macro or `<Trans>` component
2. Run `pnpm run lingui:extract` to update locale files
3. Edit the `.po` files in `locales/` to add translations

```tsx
import { t } from "@lingui/core/macro";
import { Trans } from "@lingui/react/macro";

// In component
const title = t`Welcome`;
<Trans>Click here to continue</Trans>;
```

---

## Configuration Files

| File                | Purpose                           |
| ------------------- | --------------------------------- |
| `vite.config.ts`    | Vite bundler configuration        |
| `tsconfig.json`     | TypeScript configuration          |
| `.oxfmtrc.json`     | Formatter settings                |
| `.oxlintrc.json`    | Linter settings                   |
| `drizzle.config.ts` | Drizzle ORM configuration         |
| `lingui.config.ts`  | Lingui i18n configuration         |
| `components.json`   | shadcn/ui component configuration |

---

## Contributing Guidelines

<Steps>
	<Step title="Fork & Clone">Fork the repository on GitHub and clone your fork locally.</Step>

    <Step title="Create a Branch">
    	Create a feature branch from `main`: ```bash git checkout -b feature/my-feature ```
    </Step>

    <Step title="Make Changes">Implement your changes following the patterns described above.</Step>

    <Step title="Test Locally">
    	Ensure the app works correctly with your changes: ```bash pnpm run dev pnpm run lint pnpm run typecheck ```
    </Step>

    <Step title="Commit & Push">Write clear commit messages and push to your fork.</Step>

    <Step title="Open a Pull Request">
    	Open a PR against the main repository with a clear description of your changes.
    </Step>

</Steps>

<Note>Make sure to read any `CONTRIBUTING.md` file in the repository for additional guidelines.</Note>

---

## Need Help?

<CardGroup cols={2}>
  <Card title="GitHub Discussions" icon="comments" href="https://github.com/amruthpillai/reactive-resume/discussions">
    Ask questions and discuss ideas with the community.
  </Card>
  <Card title="GitHub Issues" icon="bug" href="https://github.com/amruthpillai/reactive-resume/issues">
    Report bugs or request features.
  </Card>
</CardGroup>