igm
b27a977809
- Add test:unit, test:cov, test:unit:cov to README scripts table - Add Running Tests section to CLAUDE.md recommending test:cov Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
190 lines
5.2 KiB
Markdown
190 lines
5.2 KiB
Markdown
# Reviq Publisher Dashboard
|
|
|
|
A modern publisher dashboard for managing organizations, members, and sites. Built as a monorepo with SvelteKit frontend and oRPC API server.
|
|
|
|
## Tech Stack
|
|
|
|
### Frontend (`apps/publisher-dashboard`)
|
|
- **SvelteKit** with Svelte 5 (runes)
|
|
- **Tailwind CSS v4** for styling
|
|
- **TanStack Query** for data fetching
|
|
- **bits-ui** for accessible UI primitives
|
|
- **Lucide** for icons
|
|
- **WebAuthn/Passkeys** for passwordless authentication
|
|
|
|
### Backend (`apps/api-server`)
|
|
- **Bun** runtime
|
|
- **oRPC** for type-safe API (contract-first)
|
|
- **Kysely** for type-safe SQL queries
|
|
- **PostgreSQL** database
|
|
- **Postmark** for transactional emails
|
|
|
|
### CLI (`apps/cli`)
|
|
- **Stricli** for command parsing
|
|
- API token-based authentication
|
|
- User, organization, and site management commands
|
|
|
|
### Shared Packages
|
|
- `@reviq/api-contract` - Shared API contract (oRPC)
|
|
- `@reviq/common` - Shared utilities for frontend and backend
|
|
- `@reviq/db` - Database client and queries
|
|
- `@reviq/db-schema` - Database schema and codegen
|
|
- `@reviq/frontend-utils` - Frontend-specific utilities
|
|
- `@reviq/server-utils` - Server/CLI utilities
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
publisher-dashboard/
|
|
├── apps/
|
|
│ ├── api-server/ # Backend API server
|
|
│ ├── cli/ # Command-line interface
|
|
│ └── publisher-dashboard/ # SvelteKit frontend
|
|
├── packages/
|
|
│ ├── api-contract/ # Shared oRPC contract
|
|
│ ├── common/ # Shared utilities (frontend + backend)
|
|
│ ├── db/ # Database client
|
|
│ ├── db-schema/ # DB schema & codegen
|
|
│ ├── frontend-utils/ # Frontend utilities
|
|
│ ├── server-utils/ # Server/CLI utilities
|
|
│ └── testing/ # Test utilities
|
|
└── db/ # Database migrations
|
|
```
|
|
|
|
## Setup
|
|
|
|
### Prerequisites
|
|
|
|
- [Bun](https://bun.sh/) v1.1.42+
|
|
- [devenv](https://devenv.sh/) for development environment management
|
|
|
|
### Environment Variables
|
|
|
|
Copy `.env.dev` to `.env` for local development:
|
|
|
|
```bash
|
|
cp .env.dev .env
|
|
```
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `DATABASE_URL` | PostgreSQL connection string |
|
|
|
|
### Development
|
|
|
|
Start the development environment:
|
|
|
|
```bash
|
|
devenv up
|
|
```
|
|
|
|
This starts:
|
|
- PostgreSQL database
|
|
- Publisher dashboard dev server (port 6827)
|
|
- API server
|
|
- Package build watcher
|
|
|
|
The database is automatically initialized with:
|
|
- Database: `reviq-dashboard`
|
|
- User: `reviq`
|
|
- Password: `reviq`
|
|
|
|
### Manual Development
|
|
|
|
If not using devenv, start services individually:
|
|
|
|
```bash
|
|
# Install dependencies
|
|
bun install
|
|
|
|
# Build packages first
|
|
bun run build:packages
|
|
|
|
# Start dev server
|
|
bun run dev
|
|
```
|
|
|
|
## Scripts
|
|
|
|
| Script | Description |
|
|
|--------|-------------|
|
|
| `bun run dev` | Start all dev servers |
|
|
| `bun run build` | Build all packages and apps |
|
|
| `bun run typecheck` | Run TypeScript type checking |
|
|
| `bun run lint` | Run Biome and ESLint |
|
|
| `bun run lint:fix` | Fix linting issues |
|
|
| `bun run test` | Run all tests (requires database) |
|
|
| `bun run test:unit` | Run unit tests only (no database required) |
|
|
| `bun run test:cov` | Run all tests with coverage report |
|
|
| `bun run test:unit:cov` | Run unit tests with coverage (no database) |
|
|
| `bun run db:codegen` | Generate database types |
|
|
| `./scripts/db-dump` | Dump database schema (strips `\restrict` lines) |
|
|
| `./scripts/db-migrate` | Run migrations (strips `\restrict` lines) |
|
|
|
|
## CLI
|
|
|
|
The `@reviq/cli` package provides a command-line interface for managing users, organizations, and sites. See [apps/cli/README.md](apps/cli/README.md) for detailed usage.
|
|
|
|
Quick start:
|
|
|
|
```bash
|
|
# Build the CLI
|
|
bun run --cwd apps/cli build
|
|
|
|
# Login with an API token
|
|
./apps/cli/dist/reviq auth login --token <your-token>
|
|
|
|
# Check status
|
|
./apps/cli/dist/reviq auth status
|
|
```
|
|
|
|
## Features
|
|
|
|
### Authentication
|
|
- Passwordless login with passkeys (WebAuthn)
|
|
- Email verification
|
|
- Session management with device tracking
|
|
|
|
### Organizations
|
|
- Create and manage organizations
|
|
- Member management with roles (owner, admin, member)
|
|
- Invite members via email
|
|
- Organization settings
|
|
|
|
### Dashboard
|
|
- Organization switcher
|
|
- Performance metrics
|
|
- Reports (coming soon)
|
|
- Site management (coming soon)
|
|
|
|
## Architecture
|
|
|
|
### Frontend Routes
|
|
|
|
```
|
|
/ # Landing page
|
|
/login # Login page
|
|
/dashboard # Organization list
|
|
/dashboard/[slug] # Organization home
|
|
/dashboard/[slug]/performance # Performance metrics
|
|
/dashboard/[slug]/reports # Reports (placeholder)
|
|
/dashboard/[slug]/settings # Organization settings
|
|
├── /members # Member management
|
|
└── /sites # Sites (placeholder)
|
|
/account # User account settings
|
|
├── /security # Security settings
|
|
└── /sessions # Active sessions
|
|
/admin # Admin panel
|
|
```
|
|
|
|
### API Structure
|
|
|
|
The API uses oRPC with a contract-first approach. Routes are defined in `@reviq/api-contract` and implemented in `apps/api-server`.
|
|
|
|
Key API namespaces:
|
|
- `auth` - Authentication (passkeys, sessions)
|
|
- `me` - Current user profile
|
|
- `orgs` - Organization management
|
|
- `orgs.members` - Member management
|
|
- `orgs.invites` - Invitation management
|