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)

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

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

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:

   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:

   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

dotnet test

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