> ## Documentation Index
> Fetch the complete documentation index at: https://docs.folksbase.joselito.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Learn about the folksbase project

Hey folks! welcome to the folksbase docs. If you're reading this, you're most likely part of the Resend team. This site is the documentation for folksbase, a project I built for the Resend hiring process technical challenge.

This isn't your standard, dry technical documentation. Think of it more as a "behind the scenes" look into my thought process. I want you to read this—especially the parts explaining my choices and trade-offs—as if we were having a conversation as coworkers, maybe during a planning or a refining session.

And yes, as you can see, I'll be writing in first person from time to time. I truly believe that helps to give this feeling.

Before diving into the architecture and the "how-to," I encourage you to actually try the project. Use it as someone who's genuinely looking for a fast, simple, and reliable way to manage contacts.

<Card title="Live Demo" icon="globe" href="https://folksbase.joselito.dev">
  Try folksbase now
</Card>

## Project Structure

folksbase is a monorepo managed with pnpm and Turborepo:

```
folksbase/
├── apps/
│   ├── web/        # Next.js 15 frontend (deployed to Vercel)
│   ├── api/        # Hono backend (deployed to Render)
│   └── docs/       # This documentation site (Mintlify)
├── packages/
│   ├── db/         # Drizzle schema + migrations (shared)
│   ├── emails/     # Email templates via Resend
│   └── types/      # Shared TypeScript types
```

## Key Features

<CardGroup cols={2}>
  <Card title="CSV Import with AI Mapping" icon="file-csv">
    Upload CSV files and automatically map columns to contact fields. Review suggestions, adjust if needed, and import thousands of contacts in seconds.
  </Card>

  <Card title="Background Jobs" icon="gears">
    Large imports and exports run asynchronously via Inngest with step-level retries. No timeouts, no memory issues.
  </Card>

  <Card title="Clean REST API" icon="code">
    Auto-generated OpenAPI spec with interactive Scalar docs. Every endpoint is documented, validated with Zod, and rate-limited.
  </Card>

  <Card title="Contact Management" icon="address-book">
    Create, search, filter, and tag contacts. Full CRUD operations with cursor-based pagination for fast performance at any scale.
  </Card>

  <Card title="Tag System" icon="tags">
    Organize contacts with tags. Filter by multiple tags at once and export filtered subsets as CSV.
  </Card>

  <Card title="Dashboard" icon="chart-line">
    See stats at a glance — total contacts, growth over time, recent imports and exports, all on one page.
  </Card>
</CardGroup>

## Tech Stack at a Glance

| Layer           | Technology                                       |
| --------------- | ------------------------------------------------ |
| Frontend        | Next.js 15 (App Router, React Server Components) |
| Styling         | Tailwind CSS + Radix Primitives                  |
| Backend         | Hono v4                                          |
| Database        | Neon (Postgres serverless) via Drizzle ORM       |
| Auth            | Supabase Auth                                    |
| Background Jobs | Inngest                                          |
| AI              | Anthropic Claude Haiku (CSV column mapping)      |
| Testing         | Vitest (unit) + Playwright (E2E)                 |

For a deeper dive into the architecture, head to the [Architecture Overview](/architecture/overview).

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get folksbase running locally
  </Card>

  <Card title="Plan and Execution" icon="brain" href="/architecture/overview">
    Get an overview on why folksbase is as it is
  </Card>
</CardGroup>