{"id":34502890,"url":"https://github.com/msalahz/contactory","last_synced_at":"2026-04-01T19:02:18.728Z","repository":{"id":327831588,"uuid":"1109491210","full_name":"msalahz/contactory","owner":"msalahz","description":"[Under Development] A simple, fast, and secure way to organize all your personal and professional contacts in one place.","archived":false,"fork":false,"pushed_at":"2026-01-14T00:16:35.000Z","size":3043,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T17:56:45.183Z","etag":null,"topics":["bilingual","copilot","drizzle-orm","eslint","github-actions","i18n","neondb","playwright","postgresql","prettier","react","shadcn","ssr","t3-en","tailwindcss","tanstack","tanstack-start","typescript","vite","vitest"],"latest_commit_sha":null,"homepage":"https://contactory.consultin.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/msalahz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-03T22:00:04.000Z","updated_at":"2026-02-23T23:06:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/msalahz/contactory","commit_stats":null,"previous_names":["msalahz/contacts","msalahz/contactory"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/msalahz/contactory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msalahz%2Fcontactory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msalahz%2Fcontactory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msalahz%2Fcontactory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msalahz%2Fcontactory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/msalahz","download_url":"https://codeload.github.com/msalahz/contactory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/msalahz%2Fcontactory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31053557,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T16:55:14.406Z","status":"ssl_error","status_checked_at":"2026-03-27T16:55:07.885Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bilingual","copilot","drizzle-orm","eslint","github-actions","i18n","neondb","playwright","postgresql","prettier","react","shadcn","ssr","t3-en","tailwindcss","tanstack","tanstack-start","typescript","vite","vitest"],"created_at":"2025-12-24T02:21:43.555Z","updated_at":"2026-04-01T19:02:18.719Z","avatar_url":"https://github.com/msalahz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📇 Contactory\n\nA modern, type-safe contact management application built with TanStack Start, React 19, and Drizzle ORM. Organize all\nyour personal and professional contacts in one secure place with a beautiful, responsive interface.\n\n🔗 **[Live Demo](https://contactory.consultin.dev/)**\n\n---\n\n## 📑 Table of Contents\n\n- [Features](#-features)\n- [Tech Stack](#-tech-stack)\n- [Project Structure](#-project-structure)\n- [Getting Started](#-getting-started)\n- [Scripts](#-scripts)\n- [Code Review Workflows](#-code-review-workflows)\n- [Documentation](#-documentation)\n- [Dependencies](#-dependencies)\n- [License](#-license)\n\n---\n\n## ✨ Features\n\n| Feature              | Status         | Description                                             |\n|----------------------|----------------|---------------------------------------------------------|\n| Authentication       | ✅ Implemented  | Secure signup, signin, password reset with better-auth  |\n| Theme Support        | ✅ Implemented  | Dark/light mode with system preference detection        |\n| Internationalization | ✅ Implemented  | Bilingual support with RTL/LTR layout                   |\n| Organize Contacts    | 🚧 In Progress | CRUD operations for contacts (basic structure in place) |\n| Favorites            | 🚧 In Progress | Mark and manage favorite contacts                       |\n| Search \u0026 Filter      | 📅 Coming Soon | Real-time search with advanced filtering                |\n| Sync                 | 📅 Coming Soon | Cross-device synchronization                            |\n| Share                | 📅 Coming Soon | Share contacts via link, email or messaging             |\n| Import/Export        | 📅 Coming Soon | CSV, vCard and JSON support                             |\n| Groups/Labels        | 📅 Coming Soon | Custom groups with color coding                         |\n| Duplicate Detection  | 📅 Coming Soon | Find and merge duplicate contacts                       |\n| QR Code Sharing      | 📅 Coming Soon | Share contact info via scannable QR code                |\n\n---\n\n## 🛠️ Tech Stack\n\n### Core\n\n| Technology       | Purpose                    |\n|------------------|----------------------------|\n| TypeScript 5.9.3 | Type-safe JavaScript       |\n| Vite 7.3.0       | Build tool \u0026 dev server    |\n| TanStack Start   | Full-stack React framework |\n| React 19.2.3     | UI library                 |\n\n### Data \u0026 State\n\n| Technology      | Purpose                   |\n|-----------------|---------------------------|\n| TanStack Router | Type-safe routing         |\n| TanStack Query  | Data fetching \u0026 caching   |\n| TanStack Store  | State management \u0026 theme  |\n| TanStack Form   | Form handling             |\n| Drizzle ORM     | Database ORM (PostgreSQL) |\n| Zod             | Schema validation         |\n\n### UI/UX\n\n| Technology               | Purpose                |\n|--------------------------|------------------------|\n| Tailwind CSS 4           | Utility-first styling  |\n| shadcn/ui                | Component library      |\n| Radix UI                 | Accessible primitives  |\n| Lucide React             | Icons                  |\n| class-variance-authority | Component variants     |\n| tailwind-merge           | Merge Tailwind classes |\n\n### Authentication\n\n| Technology       | Purpose                             |\n|------------------|-------------------------------------|\n| better-auth      | Authentication \u0026 session management |\n| @t3-oss/env-core | Environment validation              |\n\n### Deployment\n\n| Technology         | Purpose             |\n|--------------------|---------------------|\n| Cloudflare Workers | Edge deployment     |\n| Wrangler           | Cloudflare CLI tool |\n\n### Development Tools\n\n| Technology      | Purpose                |\n|-----------------|------------------------|\n| Vitest          | Unit testing framework |\n| Testing Library | Component testing      |\n| ESLint          | Code linting           |\n| Prettier        | Code formatting        |\n| Drizzle Kit     | Database migrations    |\n| React Email     | Email templates        |\n| Resend          | Email delivery service |\n| Motion          | Animation library      |\n\n---\n\n## 📁 Project Structure\n\n```\ncontactory/\n├── .github/                       # GitHub configuration\n│   ├── workflows/\n│   │   └── ci.yml                # CI/CD pipeline configuration\n├── docs/                          # Documentation\n│   ├── project-overview.md       # Product vision, features, requirements\n│   └── project-architecture.md   # Technical stack, patterns, guidelines\n├── public/                        # Static assets\n│   ├── favicon.svg\n│   └── robots.txt\n├── specs/                         # Feature specifications\n│   └── 001-contacts-crud/        # Contacts CRUD feature spec\n├── src/\n│   ├── backend/                   # Server-only code\n│   │   ├── lib/                   # Business logic modules\n│   │   │   ├── auth.ts            # Auth business logic\n│   │   │   ├── contacts.ts        # Contacts business logic\n│   │   │   ├── storage.ts         # File storage logic\n│   │   │   └── theme.ts           # Theme management\n│   │   ├── middlewares/           # Server middlewares\n│   │   ├── mutations/             # Server mutation functions (RPCs)\n│   │   │   ├── auth.ts            # Auth mutations\n│   │   │   └── contacts.ts        # Contacts mutations\n│   │   ├── queries/               # Server query functions (RPCs)\n│   │   │   ├── auth.ts            # Auth queries\n│   │   │   └── contacts.ts        # Contacts queries\n│   │   └── utils/                 # Server utilities\n│   ├── core/                      # Core/reusable code\n│   │   ├── components/            # Shared UI components\n│   │   ├── locales/               # i18n translations\n│   │   ├── theme/                 # Theme system\n│   │   ├── utils/                 # Utility functions\n│   │   └── schemas.ts             # Zod schemas \u0026 TypeScript types\n│   ├── features/                  # Client feature modules\n│   │   ├── auth/                  # Authentication feature\n│   │   │   ├── components/        # Auth UI components\n│   │   │   ├── hooks/             # Auth hooks\n│   │   │   └── lib/               # Auth utilities\n│   │   ├── contacts/              # Contacts management feature\n│   │   │   ├── components/        # Contacts UI components\n│   │   │   ├── hooks/             # Contacts hooks\n│   │   │   ├── lib/               # Contacts utilities\n│   │   │   ├── keys.ts            # Query keys factory\n│   │   │   └── options.ts         # Query options factory\n│   │   └── landing/               # Landing page feature\n│   │       └── components/        # Landing page components\n│   ├── integrations/              # Third-party integrations\n│   │   ├── better-auth/           # Authentication config\n│   │   ├── drizzle/               # Drizzle client, migrations, seeds, config\n│   │   ├── i18n/                  # Internationalization setup\n│   │   ├── resend/                # Email integration \u0026 templates\n│   │   ├── shadcn/                # UI components\n│   │   ├── tanstack-form/         # Form handling\n│   │   └── tanstack-query/        # Query client setup\n│   ├── routes/                    # File-based routing\n│   │   ├── __root.tsx             # Root layout with providers\n│   │   ├── _auth/                 # Unauthenticated routes\n│   │   │   ├── sign-in.tsx        # Sign in page\n│   │   │   ├── sign-up.tsx        # Sign up page\n│   │   │   ├── forgot-password.tsx # Password reset request\n│   │   │   └── reset-password.tsx # Password reset form\n│   │   ├── _public/               # Public routes (landing)\n│   │   ├── _user/                 # Protected user routes\n│   │   │   ├── route.tsx          # User layout + auth guard\n│   │   │   ├── dashboard.tsx      # Main dashboard view\n│   │   │   ├── contacts/          # Contacts routes\n│   │   │   │   ├── index.tsx      # Contacts list\n│   │   │   │   ├── new.tsx        # Create contact sheet\n│   │   │   │   ├── $contactId.tsx # Contact detail sheet\n│   │   │   │   └── $contactId.edit.tsx # Edit contact sheet\n│   │   │   └── profile.tsx        # User profile page\n│   │   └── _admin/                # Admin-only routes\n│   ├── start.ts                   # TanStack Start configuration\n│   ├── style.css                  # Global styles with Tailwind CSS\n│   ├── env.client.ts              # Client environment variables\n│   ├── env.server.ts              # Server environment variables\n│   └── router.tsx                 # TanStack Router configuration\n├── .env.example                   # Example environment variables\n├── components.json                # shadcn/ui config\n├── drizzle.config.ts              # Drizzle ORM config\n├── eslint.config.js               # ESLint config\n├── package.json                   # Dependencies \u0026 scripts\n├── prettier.config.js             # Prettier config\n├── tsconfig.json                  # TypeScript config\n└── vite.config.ts                 # Vite config\n```\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Node.js 20+\n- pnpm 9+\n- PostgreSQL +14\n\n### Installation\n\n1. Clone the repository:\n\n   ```bash\n   git clone https://github.com/your-username/contactory.git\n   cd contactory\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   pnpm install\n   ```\n\n3. Set up environment variables:\n\n   ```bash\n   cp .env.example .env.local\n   ```\n\n   Update the `.env.local` file with your configuration.\n\n4. Run database migrations:\n\n   ```bash\n   pnpm db:migrate\n   ```\n\n5. Start the development server:\n   ```bash\n   pnpm dev\n   ```\n   The application will be available at `http://localhost:3000`\n\n### Environment Variables\n\n| Variable                           | Description                      | Required | Default                 |\n|------------------------------------|----------------------------------|----------|-------------------------|\n| `DATABASE_URL`                     | PostgreSQL connection string     | ✅        | -                       |\n| `BETTER_AUTH_SECRET`               | Secret key for authentication    | ✅        | -                       |\n| `BETTER_AUTH_URL`                  | Base URL of your app             | ✅        | `http://localhost:3000` |\n| `BETTER_AUTH_GOOGLE_CLIENT_ID`     | Google OAuth client ID           | ❌        | -                       |\n| `BETTER_AUTH_GOOGLE_CLIENT_SECRET` | Google OAuth client secret       | ❌        | -                       |\n| `RESEND_API_KEY`                   | API key for Resend email service | ❌        | -                       |\n| `VITE_BETTER_AUTH_BASE_URL`        | Client-side base URL of your app | ✅        |\n\n---\n\n## 📜 Scripts\n\n| Script              | Description                            |\n|---------------------|----------------------------------------|\n| `pnpm dev`          | Start development server (port 3000)   |\n| `pnpm build`        | Build for production                   |\n| `pnpm serve`        | Preview production build               |\n| `pnpm test`         | Run unit tests                         |\n| `pnpm test:workers` | Run Cloudflare Workers tests           |\n| `pnpm lint`         | Lint codebase                          |\n| `pnpm format`       | Format code with Prettier              |\n| `pnpm check`        | Format and lint with auto-fix          |\n| `pnpm typecheck`    | Run TypeScript type checking           |\n| `pnpm db:generate`  | Generate database migrations           |\n| `pnpm db:migrate`   | Run database migrations                |\n| `pnpm db:push`      | Push schema changes to database        |\n| `pnpm db:pull`      | Pull schema from database              |\n| `pnpm db:studio`    | Open Drizzle Studio                    |\n| `pnpm db:seeds`     | Run database seed script               |\n| `pnpm deploy`       | Build and deploy to Cloudflare Workers |\n| `pnpm cf-typegen`   | Generate Cloudflare Workers types      |\n\n---\n\n## 🔍 Code Review Workflows\n\nThis repo includes Claude/Windsurf workflows under `.windsurf/workflows/` prefixed with\n`code-review*`. These workflows follow a multi-agent code review approach (constitution\ncompliance, bug detection, security, performance) and use confidence scoring to reduce false\npositives.\n\n### Available workflows\n\n- **Project-wide review**: `code-review.project`\n    - **Use when**: You want an overall health report for the repo.\n    - **Examples**:\n        - `code-review.project`\n        - `code-review.project quick`\n        - `code-review.project focus:security`\n\n- **Pull request review**: `code-review.pr`\n    - **Use when**: Reviewing a GitHub PR via `gh`.\n    - **Examples**:\n        - `code-review.pr`\n        - `code-review.pr 123`\n\n- **Git diff review**: `code-review.git`\n    - **Use when**: Reviewing local changes without a PR.\n    - **Examples**:\n        - `code-review.git`\n        - `code-review.git staged`\n        - `code-review.git unstaged`\n        - `code-review.git HEAD~3`\n        - `code-review.git commit1..commit2`\n\n- **Pre-commit staged review**: `code-review.staged`\n    - **Use when**: Quick gate-style check before committing.\n    - **Examples**:\n        - `code-review.staged`\n        - `code-review.staged --strict`\n\n- **Feature-scope review**: `code-review.feature`\n    - **Use when**: Deep review for a feature folder (architecture, UX/i18n consistency, tests).\n    - **Examples**:\n        - `code-review.feature auth`\n        - `code-review.feature src/features/users`\n\n- **Single-file review**: `code-review.file`\n    - **Use when**: You want detailed, line-by-line feedback for one file.\n    - **Examples**:\n        - `code-review.file src/router.tsx`\n\n### What the workflows check\n\n- **Code Quality**: TypeScript strictness, lint/format consistency, error handling patterns\n- **Testing**: coverage gaps and test quality for changes\n- **UX Consistency**: i18n usage, accessibility, consistent shadcn/ui patterns\n- **Performance**: expensive imports, unnecessary re-renders, route loading patterns\n- **Security**: secrets, authz/authn correctness, input validation\n\n---\n\n## 📖 Documentation\n\n### Project Documentation\n\n- [Project Overview](docs/project-overview.md) - Product vision, features, requirements\n- [Project Architecture](docs/project-architecture.md) - High-level project structure and design decisions\n- [Contactory Constitution](.specify/memory/constitution.md) - Mandatory standards for code quality, testing, UX, and\n  performance\n\n### Specifications\n\n- [001 Contacts CRUD](specs/001-contacts-crud/spec.md)\n\n### GitHub Configuration\n\n| File                                                            | Description                                                           |\n|-----------------------------------------------------------------|-----------------------------------------------------------------------|\n| [Copilot Instructions](./.github/copilot-instructions.md)       | Code generation guidelines and project conventions for GitHub Copilot |\n| [Git Commit Instructions](./.github/git-commit-instructions.md) | Conventional commit message format and guidelines                     |\n| [CI Workflow](./.github/workflows/ci.yml)                       | GitHub Actions workflow for linting, testing and building             |\n\nThe project uses GitHub Actions for continuous integration. The pipeline runs on every push and pull request to `main`:\n\n- **Linting** – ESLint code quality checks\n- **Formatting** – Prettier format verification\n- **Type Check** – TypeScript type validation\n- **Tests** – Vitest unit test execution\n- **Build** – Production build verification\n\n---\n\n## 📦 Dependencies\n\n### Production\n\n| Package                    | Version  | Description                |\n|----------------------------|----------|----------------------------|\n| `react`                    | ^19.2.3  | UI library                 |\n| `react-dom`                | ^19.2.3  | React DOM renderer         |\n| `@tanstack/react-start`    | ^1.145.7 | Full-stack React framework |\n| `@tanstack/react-router`   | ^1.145.7 | Type-safe routing          |\n| `@tanstack/react-query`    | ^5.90.16 | Data fetching \u0026 caching    |\n| `@tanstack/react-form`     | ^1.27.7  | Form handling              |\n| `@tanstack/react-store`    | ^0.7.7   | State management \u0026 theme   |\n| `drizzle-orm`              | ^0.45.1  | Database ORM               |\n| `postgres`                 | ^3.4.7   | PostgreSQL client          |\n| `better-auth`              | ^1.4.10  | Authentication library     |\n| `zod`                      | ^4.3.5   | Schema validation          |\n| `tailwindcss`              | ^4.1.18  | CSS framework              |\n| `class-variance-authority` | ^0.7.1   | Component variants         |\n| `clsx`                     | ^2.1.1   | Class name utility         |\n| `tailwind-merge`           | ^3.4.0   | Tailwind class merging     |\n| `radix-ui`                 | ^1.4.3   | Accessible UI primitives   |\n| `lucide-react`             | ^0.544.0 | Icon library               |\n| `motion`                   | ^12.24.0 | Animation library          |\n| `@t3-oss/env-core`         | ^0.13.10 | Type-safe env variables    |\n| `uuid`                     | ^13.0.0  | UUID generation            |\n\n### Development\n\n| Package                   | Version | Description               |\n|---------------------------|---------|---------------------------|\n| `typescript`              | ^5.9.3  | TypeScript compiler       |\n| `vite`                    | ^7.3.0  | Build tool                |\n| `vitest`                  | ^3.2.4  | Test runner               |\n| `@testing-library/react`  | ^16.3.1 | Component testing         |\n| `eslint`                  | ^9.39.2 | Linting                   |\n| `prettier`                | ^3.7.4  | Code formatting           |\n| `drizzle-kit`             | ^0.31.8 | Drizzle CLI tools         |\n| `@cloudflare/vite-plugin` | ^1.17.1 | Cloudflare Workers plugin |\n| `wrangler`                | ^4.54.0 | Cloudflare CLI            |\n\n---\n\n## 📄 License\n\nThis project is private.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsalahz%2Fcontactory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsalahz%2Fcontactory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsalahz%2Fcontactory/lists"}