# PingCAP Social Hub

PingCAP Social Hub is a Next.js social media operations platform for planning, approving, scheduling, and analyzing content across multiple networks. It combines a modern editorial UI with workflow automation, regional scheduling logic, and webhook-driven content ingestion.

This repository contains the product code and a small set of technical reference docs. Internal runbooks, QA logs, and company-specific working notes have been removed from the public version.

## Features

- Multi-step publishing workflow with draft, scheduled, published, failed, and approval states
- Calendar, queue, approvals, analytics, campaigns, inbox, and listening views
- Region-aware scheduling with configurable content tracks and posting windows
- HubSpot webhook ingestion and translation into normalized post records
- OAuth-based social account connections and encrypted token storage
- Prisma ORM on top of TiDB Cloud Serverless

## Stack

- Next.js 16 App Router
- TypeScript
- Prisma ORM
- TiDB Cloud Serverless
- NextAuth
- Playwright and Vitest

## Project Structure

```text
app/           Next.js routes and pages
components/    UI components
lib/           Business logic, auth, scheduler, integrations
prisma/        Database schema and migrations
scripts/       Utility and maintenance scripts
docs/          Public technical reference docs
playwright/    End-to-end tests
```

## Quick Start

### Prerequisites

- Node.js 20+
- npm
- A MySQL-compatible database such as TiDB Cloud Serverless
- OAuth credentials for any providers you want to enable

### Install

```bash
npm install
```

### Configure environment

```bash
cp .env.example .env
```

Fill in the values you need for your local setup.

### Prepare the database

For local development:

```bash
npx prisma generate
npx prisma migrate dev
```

### Run the app

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000).

## Environment Variables

See `.env.example` for the full template. The most important values are:

- `DATABASE_URL`
- `NEXTAUTH_SECRET`
- `NEXTAUTH_URL`
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- `ENCRYPTION_KEY`
- `TEST_AUTH_SECRET`
- `TEST_API_KEY`

Optional integrations include HubSpot, Twitter/X, LinkedIn, Facebook, and Slack.

For allowed-email messaging, keep these two values aligned:

- `ALLOWED_EMAIL_DOMAIN`: server-side access control
- `NEXT_PUBLIC_ALLOWED_EMAIL_DOMAIN`: client-side display text baked into the frontend build

## Scripts

Common commands:

```bash
npm run dev
npm run build
npm run start
npm run lint
npx tsc --noEmit
```

## Deployment

- Pushes to `main` auto-deploy to the Fly production app `pingcap-social`
- Pushes to `staging` auto-deploy to the shared Fly staging app `pingcap-social-staging`
- GitHub Actions `workflow_dispatch` can be used to manually re-deploy either environment
- Release deployments first run Prisma validation, lint, and production build checks
- After deploy, the workflow verifies the environment health endpoint from the environment variable `APP_HEALTH_URL`
- GitHub should use environment-scoped `FLY_API_TOKEN` secrets for `staging` and `production`
- GitHub Environments should also define `NEXT_PUBLIC_ALLOWED_EMAIL_DOMAIN` when the frontend should show the allowed email domain
- Protect `main` and `staging` branches and require pull requests before merge
- Use GitHub Environment approvals for `production`

### Shared Environment Database Rule

For local development, use:

```bash
npx prisma migrate dev
```

For shared `staging` and `production`, use:

```bash
npx prisma migrate deploy
```

Do not use `db push` as the standard database workflow.

Workflow files live under `.github/workflows/`.

## Notes

- This app includes test-only login and API helpers behind environment flags and secrets.
- Some product behaviors are still PingCAP-oriented by default, such as naming and workflow assumptions, but the codebase is now organized as a cleaner public reference.
- Deploy however you prefer for your environment; the repository no longer assumes access to internal deployment credentials.

## License

Add the license that matches how you want to publish the project.