# GEMINI.md

This file provides guidance to Gemini when working with code in this repository.

## Project Overview

**Teklifsat Platform**: A multi-tenant AI lead generation platform that automates the prospecting pipeline from LinkedIn search to AI-powered qualification and outreach. It uses Unipile for LinkedIn API integration and Next.js/Supabase as its core stack.

---

## Tech Stack

| Technology     | Purpose                                         |
| -------------- | ----------------------------------------------- |
| **Next.js**    | Frontend framework (App Router)                 |
| **Supabase**   | Database, Auth, Realtime, Edge Functions        |
| **TypeScript** | Static typing and enhanced developer experience |
| **Tailwind**   | Styling and responsive design                   |
| **Radix UI**   | Accessible UI primitives                        |
| **Lucide**     | Icon set                                        |
| **Playwright** | End-to-end testing                              |
| **Unipile**    | LinkedIn Multi-account API integration          |

---

## Commands

```bash
# Development
npm run dev

# Build
npm run build

# Start Production
npm run start

# Lint
npm run lint

# Documentation (refer to docs/)
# Migrations (refer to migrations/)
```

---

## Project Structure

```
app/              # Next.js App Router (Routes, API, Layouts)
├── api/          # Backend API routes
├── auth/         # Authentication flow
├── dashboard/    # Dashboard pages and logic
└── onboarding/   # User onboarding steps
components/       # UI and feature components
├── ui/           # Radix-based UI building blocks
└── ...           # Feature-specific components (auth, linkedin)
lib/              # Shared logic and libraries
├── supabase/     # Supabase client and server-side utilities
└── utils.ts      # UI helper functions (cn)
migrations/       # Database schema migrations
e2e/              # Playwright E2E tests
docs/             # Project documentation
```

---

## Architecture

The application follows the **Next.js App Router** patterns with server/client component separation.

- **Frontend**: React client components for interactive UI, Server Components for data fetching.
- **Backend API**: Next.js API routes handling business logic and integration with external APIs (Unipile, AI models).
- **Data Layer**: Supabase for relational data, authentication, and file storage.
- **Flow**: Multi-tenant data model where organizations/teams manage campaigns, leads, and outreach.

---

## Code Patterns

### UI & Styling

- Use the `cn` utility from `lib/utils.ts` for dynamic class merging.
- Prefer Radix UI primitives and Tailwind CSS for custom components.
- Maintain consistency with the `globals.css` variable-based theme system.

### Database & Auth

- Use `lib/supabase/server.ts` for server-side actions/routes.
- Use `lib/supabase/client.ts` for interactive client components.
- Leverage Supabase Auth for user identity and organization-based access control.

---

## Testing

- **E2E Tests**: Located in `e2e/`, using Playwright.
- **Run tests**: `npx playwright test`

---

## Key Files

| File                     | Purpose                                       |
| ------------------------ | --------------------------------------------- |
| `app/layout.tsx`         | Global structure and context providers.       |
| `lib/supabase/server.ts` | Supabase server-side client factory.          |
| `lib/supabase/client.ts` | Supabase browser-side client factory.         |
| `package.json`           | Dependency management and script definitions. |
| `tailwind.config.ts`     | UI theme and styling configuration.           |

---

## AI Agent Guidelines

- **Database Operations**: GEMINI / Antigravity has access to the `supabase-mcp` server. This tool **must** be used for all database-related operations, including schema exploration, table creation, and performing queries, to ensure accuracy and consistency with the Supabase environment.

---