4f0f997c32
Local dev and the test suite previously defaulted to the live production Neon database, and running the tests mutated prod data. Add guardrails plus a proper local Postgres + migrations workflow so production can't be hit by mistake: - docker-compose: local Postgres 17 (matches prod) + auto-created teqo_test - dev guard refuses a non-local DATABASE_URL; tests refuse non-_test databases - .env.test isolates the suite; vitest/playwright load it and fail closed - Payload migrations set up (push disabled); build runs `payload migrate`, so deploys apply pending migrations to prod automatically - baseline `initial` migration + idempotent consent.text varchar->jsonb fix - `pnpm db:pull` copies prod content locally, excluding supporter PII - docs (README, AGENTS.md) + agent skills for the local-db/migration workflow
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# Teqo
|
|
|
|
Teqo starts as the official digital platform for **deputado Jorge Solla** and evolves into a **white-label civic engagement platform** for politicians in Brazil.
|
|
|
|
The goal is to help political teams build direct, durable relationships with their base without depending on Big Tech social platforms as the primary channel.
|
|
|
|
## Mission
|
|
|
|
- Strengthen direct communication between representatives and citizens.
|
|
- Reduce platform dependency risk by owning audience and data channels.
|
|
- Provide reusable building blocks so each political team can launch quickly.
|
|
|
|
## Product Direction
|
|
|
|
### Phase 1: Jorge Solla Website
|
|
|
|
Initial delivery focuses on Jorge Solla's public website and communication workflows:
|
|
|
|
- Public-facing content and updates
|
|
- Institutional pages and biography
|
|
- Media and campaign communication assets
|
|
- Editorial operations through Payload CMS
|
|
|
|
### Phase 2: White-Label Platform
|
|
|
|
Teqo then becomes a configurable base product for other politicians in Brazil:
|
|
|
|
- Multi-tenant and reusable architecture
|
|
- Brand and content customization per mandate/campaign
|
|
- Shared core modules for communication and engagement
|
|
- Operational autonomy with self-hosted owned channels
|
|
|
|
## Local Development
|
|
|
|
> **Production safety:** the production database is a live Neon Postgres holding real citizens' data. Local development and tests run against a **local** Postgres and must never point at production. `pnpm dev` refuses to start against a non-local database, and the test suite refuses any database whose name doesn't end in `_test`.
|
|
|
|
### First-time setup
|
|
|
|
1. Install dependencies: `pnpm install`
|
|
2. Create your env file: `cp .env.example .env.local`
|
|
3. Start Docker, then start the local database: `pnpm db:start`
|
|
- This runs Postgres 17 (matching production) and auto-creates a `teqo_test` database for the test suite.
|
|
4. Make sure `DATABASE_URL` in `.env.local` points at local:
|
|
```
|
|
DATABASE_URL=postgresql://teqo:teqo@localhost:5432/teqo
|
|
```
|
|
5. Load a schema + content into the local database — pick one:
|
|
- **Mirror production content (recommended):** `PROD_DATABASE_URL="<unpooled Neon URL>" pnpm db:pull`
|
|
Copies production's schema and content into local. It only reads production and **excludes supporter PII** (`contact`/`signature`/`subscription` data).
|
|
- **Empty schema from migrations:** `pnpm migrate`
|
|
6. Start the dev server: `pnpm dev`
|
|
7. Open: `http://localhost:3000`
|
|
|
|
Useful scripts: `pnpm db:start` / `pnpm db:stop` (local Postgres), `pnpm db:pull` (refresh local content from prod).
|
|
|
|
### Database migrations
|
|
|
|
Schema is managed by committed Payload migrations (`src/migrations/`); `push` is disabled everywhere.
|
|
|
|
To change the schema:
|
|
|
|
1. Edit the collection/global/field config.
|
|
2. Generate a migration: `pnpm migrate:create <name>`
|
|
3. Review and commit the generated files in `src/migrations/` (both `.ts` and `.json`, plus `index.ts`).
|
|
4. Apply it locally: `pnpm migrate` (check status anytime with `pnpm migrate:status`).
|
|
|
|
**Deploying to production:** `pnpm build` runs `payload migrate` before building, so every Vercel deploy automatically applies pending migrations to the production database. Do not run migrations against production by hand.
|
|
|
|
### Running tests
|
|
|
|
Tests use the isolated `teqo_test` database (config in `.env.test`). Prepare its schema once with:
|
|
|
|
```
|
|
DATABASE_URL=postgresql://teqo:teqo@localhost:5432/teqo_test pnpm migrate
|
|
```
|
|
|
|
Then run `pnpm test` (or `pnpm test:int` / `pnpm test:e2e`).
|
|
|
|
## Tech Stack
|
|
|
|
- Payload CMS
|
|
- Next.js
|
|
- PostgreSQL (via `@payloadcms/db-postgres`)
|
|
- TypeScript
|
|
|
|
## Roadmap Notes
|
|
|
|
- Prioritize audience ownership and portability of data.
|
|
- Keep modules generic enough for reuse across different political contexts.
|
|
- Default to secure, access-controlled features for campaign and institutional teams.
|