# North West SEO

**Automated SEO Management Platform** — a multi-tenant SaaS that audits customer
websites, finds SEO opportunities, and prepares safe, reversible improvements.

- Production: `https://seo.northwestcar.group`
- Stack: Next.js 16 (App Router) · TypeScript · Tailwind CSS 4 · PostgreSQL + Prisma 6 · Redis + BullMQ · pino

## Quick start (development)

```bash
# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# edit .env — see ENVIRONMENT.md

# 3. Start infrastructure (choose one)
docker compose up -d db redis          # Docker
npx prisma dev -n northwest-seo --detach   # or Prisma's local Postgres (no Docker; no Redis)

# 4. Migrate and (optionally) seed demo data
npm run db:migrate
npm run db:seed                        # demo login: demo@example.com / demo-Password-1

# 5. Run
npm run dev                            # web app  → http://localhost:3000
npm run worker                         # background worker (crawls) — requires Redis
```

Without Redis the app runs fully except background crawls, which fail fast with
a visible "queue unavailable" message.

## Commands

| Command | Purpose |
| --- | --- |
| `npm run dev` / `build` / `start` | Next.js dev / production build / serve |
| `npm run worker` | Start the BullMQ crawl worker |
| `npm test` | Run the vitest suite |
| `npm run typecheck` / `lint` | TypeScript / ESLint |
| `npm run db:migrate` | Create + apply dev migrations |
| `npm run db:migrate:deploy` | Apply migrations in production |
| `npm run db:seed` | Seed removable demo data |
| `npm run db:studio` | Prisma Studio |

## Project documentation

| File | Contents |
| --- | --- |
| [PRODUCT_SPEC.md](PRODUCT_SPEC.md) | What the platform does and for whom |
| [ARCHITECTURE.md](ARCHITECTURE.md) | System design and folder structure |
| [DATABASE.md](DATABASE.md) | Data model and tenancy rules |
| [API.md](API.md) | HTTP API reference |
| [SECURITY.md](SECURITY.md) | Security model and controls |
| [DEPLOYMENT.md](DEPLOYMENT.md) | Production deployment runbook |
| [TESTING.md](TESTING.md) | Test strategy and commands |
| [TASKS.md](TASKS.md) | Work tracker |
| [DECISIONS.md](DECISIONS.md) | Architecture decision records |
| [ENVIRONMENT.md](ENVIRONMENT.md) | Every environment variable |
| [CHANGELOG.md](CHANGELOG.md) | Notable changes |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Working conventions |

## Product principles

1. Security, tenant isolation and data accuracy come first.
2. Every published change is recorded and reversible.
3. No fabricated metrics — unavailable data is shown as unavailable.
4. No black-hat SEO, no guaranteed-ranking claims.
5. Failures are visible to users, with recovery paths.
