A modern, type-safe contact management application built with TanStack Start, React 19, and Drizzle ORM. Organize all your personal and professional contacts in one secure place with a beautiful, responsive interface.
- Features
- Tech Stack
- Project Structure
- Getting Started
- Scripts
- Code Review Workflows
- Documentation
- Dependencies
- License
| Feature | Status | Description |
|---|---|---|
| Authentication | ✅ Implemented | Secure signup, signin, password reset with better-auth |
| Theme Support | ✅ Implemented | Dark/light mode with system preference detection |
| Internationalization | ✅ Implemented | Bilingual support with RTL/LTR layout |
| Organize Contacts | 🚧 In Progress | CRUD operations for contacts (basic structure in place) |
| Favorites | 🚧 In Progress | Mark and manage favorite contacts |
| Search & Filter | 📅 Coming Soon | Real-time search with advanced filtering |
| Sync | 📅 Coming Soon | Cross-device synchronization |
| Share | 📅 Coming Soon | Share contacts via link, email or messaging |
| Import/Export | 📅 Coming Soon | CSV, vCard and JSON support |
| Groups/Labels | 📅 Coming Soon | Custom groups with color coding |
| Duplicate Detection | 📅 Coming Soon | Find and merge duplicate contacts |
| QR Code Sharing | 📅 Coming Soon | Share contact info via scannable QR code |
| Technology | Purpose |
|---|---|
| TypeScript 5.9.3 | Type-safe JavaScript |
| Vite 7.3.0 | Build tool & dev server |
| TanStack Start | Full-stack React framework |
| React 19.2.3 | UI library |
| Technology | Purpose |
|---|---|
| TanStack Router | Type-safe routing |
| TanStack Query | Data fetching & caching |
| TanStack Store | State management & theme |
| TanStack Form | Form handling |
| Drizzle ORM | Database ORM (PostgreSQL) |
| Zod | Schema validation |
| Technology | Purpose |
|---|---|
| Tailwind CSS 4 | Utility-first styling |
| shadcn/ui | Component library |
| Radix UI | Accessible primitives |
| Lucide React | Icons |
| class-variance-authority | Component variants |
| tailwind-merge | Merge Tailwind classes |
| Technology | Purpose |
|---|---|
| better-auth | Authentication & session management |
| @t3-oss/env-core | Environment validation |
| Technology | Purpose |
|---|---|
| Cloudflare Workers | Edge deployment |
| Wrangler | Cloudflare CLI tool |
| Technology | Purpose |
|---|---|
| Vitest | Unit testing framework |
| Testing Library | Component testing |
| ESLint | Code linting |
| Prettier | Code formatting |
| Drizzle Kit | Database migrations |
| React Email | Email templates |
| Resend | Email delivery service |
| Motion | Animation library |
contactory/
├── .github/ # GitHub configuration
│ ├── workflows/
│ │ └── ci.yml # CI/CD pipeline configuration
├── docs/ # Documentation
│ ├── project-overview.md # Product vision, features, requirements
│ └── project-architecture.md # Technical stack, patterns, guidelines
├── public/ # Static assets
│ ├── favicon.svg
│ └── robots.txt
├── specs/ # Feature specifications
│ └── 001-contacts-crud/ # Contacts CRUD feature spec
├── src/
│ ├── backend/ # Server-only code
│ │ ├── lib/ # Business logic modules
│ │ │ ├── auth.ts # Auth business logic
│ │ │ ├── contacts.ts # Contacts business logic
│ │ │ ├── storage.ts # File storage logic
│ │ │ └── theme.ts # Theme management
│ │ ├── middlewares/ # Server middlewares
│ │ ├── mutations/ # Server mutation functions (RPCs)
│ │ │ ├── auth.ts # Auth mutations
│ │ │ └── contacts.ts # Contacts mutations
│ │ ├── queries/ # Server query functions (RPCs)
│ │ │ ├── auth.ts # Auth queries
│ │ │ └── contacts.ts # Contacts queries
│ │ └── utils/ # Server utilities
│ ├── core/ # Core/reusable code
│ │ ├── components/ # Shared UI components
│ │ ├── locales/ # i18n translations
│ │ ├── theme/ # Theme system
│ │ ├── utils/ # Utility functions
│ │ └── schemas.ts # Zod schemas & TypeScript types
│ ├── features/ # Client feature modules
│ │ ├── auth/ # Authentication feature
│ │ │ ├── components/ # Auth UI components
│ │ │ ├── hooks/ # Auth hooks
│ │ │ └── lib/ # Auth utilities
│ │ ├── contacts/ # Contacts management feature
│ │ │ ├── components/ # Contacts UI components
│ │ │ ├── hooks/ # Contacts hooks
│ │ │ ├── lib/ # Contacts utilities
│ │ │ ├── keys.ts # Query keys factory
│ │ │ └── options.ts # Query options factory
│ │ └── landing/ # Landing page feature
│ │ └── components/ # Landing page components
│ ├── integrations/ # Third-party integrations
│ │ ├── better-auth/ # Authentication config
│ │ ├── drizzle/ # Drizzle client, migrations, seeds, config
│ │ ├── i18n/ # Internationalization setup
│ │ ├── resend/ # Email integration & templates
│ │ ├── shadcn/ # UI components
│ │ ├── tanstack-form/ # Form handling
│ │ └── tanstack-query/ # Query client setup
│ ├── routes/ # File-based routing
│ │ ├── __root.tsx # Root layout with providers
│ │ ├── _auth/ # Unauthenticated routes
│ │ │ ├── sign-in.tsx # Sign in page
│ │ │ ├── sign-up.tsx # Sign up page
│ │ │ ├── forgot-password.tsx # Password reset request
│ │ │ └── reset-password.tsx # Password reset form
│ │ ├── _public/ # Public routes (landing)
│ │ ├── _user/ # Protected user routes
│ │ │ ├── route.tsx # User layout + auth guard
│ │ │ ├── dashboard.tsx # Main dashboard view
│ │ │ ├── contacts/ # Contacts routes
│ │ │ │ ├── index.tsx # Contacts list
│ │ │ │ ├── new.tsx # Create contact sheet
│ │ │ │ ├── $contactId.tsx # Contact detail sheet
│ │ │ │ └── $contactId.edit.tsx # Edit contact sheet
│ │ │ └── profile.tsx # User profile page
│ │ └── _admin/ # Admin-only routes
│ ├── start.ts # TanStack Start configuration
│ ├── style.css # Global styles with Tailwind CSS
│ ├── env.client.ts # Client environment variables
│ ├── env.server.ts # Server environment variables
│ └── router.tsx # TanStack Router configuration
├── .env.example # Example environment variables
├── components.json # shadcn/ui config
├── drizzle.config.ts # Drizzle ORM config
├── eslint.config.js # ESLint config
├── package.json # Dependencies & scripts
├── prettier.config.js # Prettier config
├── tsconfig.json # TypeScript config
└── vite.config.ts # Vite config
- Node.js 20+
- pnpm 9+
- PostgreSQL +14
-
Clone the repository:
git clone https://github.com/your-username/contactory.git cd contactory -
Install dependencies:
pnpm install
-
Set up environment variables:
cp .env.example .env.local
Update the
.env.localfile with your configuration. -
Run database migrations:
pnpm db:migrate
-
Start the development server:
pnpm dev
The application will be available at
http://localhost:3000
| Variable | Description | Required | Default |
|---|---|---|---|
DATABASE_URL |
PostgreSQL connection string | ✅ | - |
BETTER_AUTH_SECRET |
Secret key for authentication | ✅ | - |
BETTER_AUTH_URL |
Base URL of your app | ✅ | http://localhost:3000 |
BETTER_AUTH_GOOGLE_CLIENT_ID |
Google OAuth client ID | ❌ | - |
BETTER_AUTH_GOOGLE_CLIENT_SECRET |
Google OAuth client secret | ❌ | - |
RESEND_API_KEY |
API key for Resend email service | ❌ | - |
VITE_BETTER_AUTH_BASE_URL |
Client-side base URL of your app | ✅ |
| Script | Description |
|---|---|
pnpm dev |
Start development server (port 3000) |
pnpm build |
Build for production |
pnpm serve |
Preview production build |
pnpm test |
Run unit tests |
pnpm test:workers |
Run Cloudflare Workers tests |
pnpm lint |
Lint codebase |
pnpm format |
Format code with Prettier |
pnpm check |
Format and lint with auto-fix |
pnpm typecheck |
Run TypeScript type checking |
pnpm db:generate |
Generate database migrations |
pnpm db:migrate |
Run database migrations |
pnpm db:push |
Push schema changes to database |
pnpm db:pull |
Pull schema from database |
pnpm db:studio |
Open Drizzle Studio |
pnpm db:seeds |
Run database seed script |
pnpm deploy |
Build and deploy to Cloudflare Workers |
pnpm cf-typegen |
Generate Cloudflare Workers types |
This repo includes Claude/Windsurf workflows under .windsurf/workflows/ prefixed with
code-review*. These workflows follow a multi-agent code review approach (constitution
compliance, bug detection, security, performance) and use confidence scoring to reduce false
positives.
-
Project-wide review:
code-review.project- Use when: You want an overall health report for the repo.
- Examples:
code-review.projectcode-review.project quickcode-review.project focus:security
-
Pull request review:
code-review.pr- Use when: Reviewing a GitHub PR via
gh. - Examples:
code-review.prcode-review.pr 123
- Use when: Reviewing a GitHub PR via
-
Git diff review:
code-review.git- Use when: Reviewing local changes without a PR.
- Examples:
code-review.gitcode-review.git stagedcode-review.git unstagedcode-review.git HEAD~3code-review.git commit1..commit2
-
Pre-commit staged review:
code-review.staged- Use when: Quick gate-style check before committing.
- Examples:
code-review.stagedcode-review.staged --strict
-
Feature-scope review:
code-review.feature- Use when: Deep review for a feature folder (architecture, UX/i18n consistency, tests).
- Examples:
code-review.feature authcode-review.feature src/features/users
-
Single-file review:
code-review.file- Use when: You want detailed, line-by-line feedback for one file.
- Examples:
code-review.file src/router.tsx
- Code Quality: TypeScript strictness, lint/format consistency, error handling patterns
- Testing: coverage gaps and test quality for changes
- UX Consistency: i18n usage, accessibility, consistent shadcn/ui patterns
- Performance: expensive imports, unnecessary re-renders, route loading patterns
- Security: secrets, authz/authn correctness, input validation
- Project Overview - Product vision, features, requirements
- Project Architecture - High-level project structure and design decisions
- Contactory Constitution - Mandatory standards for code quality, testing, UX, and performance
| File | Description |
|---|---|
| Copilot Instructions | Code generation guidelines and project conventions for GitHub Copilot |
| Git Commit Instructions | Conventional commit message format and guidelines |
| CI Workflow | GitHub Actions workflow for linting, testing and building |
The project uses GitHub Actions for continuous integration. The pipeline runs on every push and pull request to main:
- Linting – ESLint code quality checks
- Formatting – Prettier format verification
- Type Check – TypeScript type validation
- Tests – Vitest unit test execution
- Build – Production build verification
| Package | Version | Description |
|---|---|---|
react |
^19.2.3 | UI library |
react-dom |
^19.2.3 | React DOM renderer |
@tanstack/react-start |
^1.145.7 | Full-stack React framework |
@tanstack/react-router |
^1.145.7 | Type-safe routing |
@tanstack/react-query |
^5.90.16 | Data fetching & caching |
@tanstack/react-form |
^1.27.7 | Form handling |
@tanstack/react-store |
^0.7.7 | State management & theme |
drizzle-orm |
^0.45.1 | Database ORM |
postgres |
^3.4.7 | PostgreSQL client |
better-auth |
^1.4.10 | Authentication library |
zod |
^4.3.5 | Schema validation |
tailwindcss |
^4.1.18 | CSS framework |
class-variance-authority |
^0.7.1 | Component variants |
clsx |
^2.1.1 | Class name utility |
tailwind-merge |
^3.4.0 | Tailwind class merging |
radix-ui |
^1.4.3 | Accessible UI primitives |
lucide-react |
^0.544.0 | Icon library |
motion |
^12.24.0 | Animation library |
@t3-oss/env-core |
^0.13.10 | Type-safe env variables |
uuid |
^13.0.0 | UUID generation |
| Package | Version | Description |
|---|---|---|
typescript |
^5.9.3 | TypeScript compiler |
vite |
^7.3.0 | Build tool |
vitest |
^3.2.4 | Test runner |
@testing-library/react |
^16.3.1 | Component testing |
eslint |
^9.39.2 | Linting |
prettier |
^3.7.4 | Code formatting |
drizzle-kit |
^0.31.8 | Drizzle CLI tools |
@cloudflare/vite-plugin |
^1.17.1 | Cloudflare Workers plugin |
wrangler |
^4.54.0 | Cloudflare CLI |
This project is private.