# InboxIntel — Inbox Intelligence Platform

A Gmail analytics, cleanup, and automation app. Connects via Google OAuth2, syncs your inbox into PostgreSQL, and gives you a draggable analytics dashboard, safe bulk cleanup, unsubscribe management, optional AI analysis, advanced search, and PDF/CSV/JSON exports.

This repository is a full-stack **scaffold** structured for the 15-step implementation plan. Every layer is wired and compiles; the business logic is functional, with a few integration points (Gmail parsing edge cases, AI prompt tuning) intentionally left as clearly-marked extension points.

## Architecture

Clean Architecture across four backend projects plus a React SPA:

```
src/
  InboxIntel.Domain          Entities + enums. No external dependencies.
  InboxIntel.Application      Service interfaces, DTOs, validators, query parser.
  InboxIntel.Infrastructure   EF Core, Gmail client, sync worker, AI, export.
  InboxIntel.Api              ASP.NET Core Web API: auth, controllers, DI, Serilog.
frontend/                     React + Vite dashboard (Chart.js, react-grid-layout).
tests/                        Unit + integration test projects.
```

Dependency rule: `Api -> Infrastructure -> Application -> Domain`. Controllers contain no business logic; they delegate to Application-layer service interfaces resolved through DI.

See `docs/ARCHITECTURE.md` for the full design, data model, and request flow.

## Tech stack

.NET 8 / ASP.NET Core, EF Core + Npgsql (PostgreSQL), Hosted background worker, Serilog, FluentValidation, Polly (retry + backoff), Google.Apis.Gmail, QuestPDF/CsvHelper for exports, React 18 + Vite + Chart.js + react-grid-layout.

## Running with Docker (recommended)

```bash
cp .env.example .env          # then fill in Google OAuth credentials
docker compose up --build
```

Services: PostgreSQL (5432), API (8080), frontend (8081). Optional reverse proxy:

```bash
docker compose --profile proxy up --build   # everything on port 80
```

The API applies EF migrations automatically on startup (`Database:AutoMigrate`).

## Running locally (without Docker)

1. Start PostgreSQL and set the connection string in `src/InboxIntel.Api/appsettings.Development.json`.
2. Create the initial migration and database:

   ```bash
   dotnet tool install --global dotnet-ef
   dotnet ef migrations add InitialCreate \
     -p src/InboxIntel.Infrastructure -s src/InboxIntel.Api
   dotnet ef database update -p src/InboxIntel.Infrastructure -s src/InboxIntel.Api
   ```

3. Run the API and the frontend:

   ```bash
   dotnet run --project src/InboxIntel.Api        # http://localhost:5080
   cd frontend && npm install && npm run dev      # http://localhost:5173
   ```

## Google OAuth2 setup

Create an OAuth client (type: Web application) in the Google Cloud Console. Add the Gmail API. Authorized redirect URI: `http://localhost:5080/signin-google` (dev) and your production URL. Put the client id/secret in `.env` or user-secrets. Scopes requested: `openid email profile gmail.readonly gmail.modify` (no send scope).

## Security notes

OAuth refresh tokens are encrypted at rest with the ASP.NET Core Data Protection API (AES) and never logged. Keys persist to a mounted `/keys` volume. All destructive cleanup and unsubscribe actions require an explicit `Confirmed` flag and a server-side preview. The AI layer is advisory only — it never performs destructive actions.

## Tests

```bash
dotnet test
```

Unit tests cover the Gmail query parser and unsubscribe extraction; integration tests boot the API host and assert authorization is enforced.