# Local Setup Guide

This project runs a React dashboard, a Node/Express API, and a local PGlite database stored inside the project folder.

## Requirements

- Node.js 20 or newer
- pnpm

Check versions:

```powershell
node -v
pnpm.cmd -v
```

## Setup From ZIP

1. Extract the project ZIP.
2. Open PowerShell in the project root.
3. Install dependencies:

```powershell
pnpm.cmd install --ignore-scripts
```

4. Create a local env file:

```powershell
copy .env.example .env
```

5. Confirm `.env` has these local values:

```env
WEB_PORT=21324
API_PORT=8081
BASE_PATH=/
API_PROXY_TARGET=http://localhost:8081
DATABASE_URL=pglite://.local/pglite
```

6. Add optional integration keys if needed:

```env
LINKEDIN_ACCESS_TOKEN=
TELEGRAM_BOT_TOKEN=
GROQ_API_KEY=
```

## Run Locally

Start the API in one terminal:

```powershell
pnpm.cmd --filter @workspace/api-server run dev
```

Start the dashboard in another terminal:

```powershell
pnpm.cmd --filter @workspace/linkedin-bot run dev
```

Open:

```text
http://localhost:21324
```

API runs at:

```text
http://localhost:8081
```

Frontend API proxy:

```text
http://localhost:21324/api/healthz
```

## Local Database

The local database is stored here:

```text
.local/pglite
```

The API creates required tables automatically on startup.

If you want a fresh empty database, stop the API and delete:

```text
.local/pglite
```

Then start the API again.

## Sharing The Project

Do not share your real `.env` file.

Share:

```text
.env.example
```

Do not include `.local/pglite` unless you intentionally want to share local database data.

If `.local/pglite` is not included, the receiving user gets a fresh empty database automatically.

## Common Issues

### PowerShell blocks pnpm

Use:

```powershell
pnpm.cmd
```

instead of:

```powershell
pnpm
```

### Frontend native package error

If Vite complains about missing native packages such as Rollup, run:

```powershell
pnpm.cmd add -Dw @rollup/rollup-win32-x64-msvc lightningcss-win32-x64-msvc @tailwindcss/oxide-win32-x64-msvc --ignore-scripts
```

### Port Already In Use

Default ports:

```text
Frontend: 21324
API: 8081
```

Change them in `.env`:

```env
WEB_PORT=21324
API_PORT=8081
API_PROXY_TARGET=http://localhost:8081
```

### Database 500 Error

Make sure `.env` uses the local database:

```env
DATABASE_URL=pglite://.local/pglite
```

Then restart the API.

### Hosted Postgres Alternative

If you want to use Neon/Supabase/Postgres instead of local PGlite, use:

```env
DATABASE_URL=postgresql://USER:PASSWORD@HOST/DATABASE?sslmode=require
```

Then push schema:

```powershell
pnpm.cmd --filter @workspace/db run push
```

## Backup Notes

`pg_dump` works for hosted or installed PostgreSQL databases.

It does not work with the local `pglite://.local/pglite` database path.

Run backup for hosted Postgres:

```powershell
pnpm.cmd run db:backup
```