{"id":31730376,"url":"https://github.com/megatron-xcoder/buyer-lead-intake","last_synced_at":"2025-10-09T07:28:05.661Z","repository":{"id":315073687,"uuid":"1057968278","full_name":"Megatron-XCoder/Buyer-Lead-Intake","owner":"Megatron-XCoder","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-16T14:30:16.000Z","size":121,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-16T15:46:38.687Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://buyer-lead-intake-silk.vercel.app","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/Megatron-XCoder.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-09-16T12:56:29.000Z","updated_at":"2025-09-16T14:31:51.000Z","dependencies_parsed_at":"2025-09-16T15:46:41.914Z","dependency_job_id":"d432322e-f119-477c-857a-af88b8d8bbaf","html_url":"https://github.com/Megatron-XCoder/Buyer-Lead-Intake","commit_stats":null,"previous_names":["megatron-xcoder/buyer-lead-intake"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Megatron-XCoder/Buyer-Lead-Intake","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Megatron-XCoder%2FBuyer-Lead-Intake","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Megatron-XCoder%2FBuyer-Lead-Intake/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Megatron-XCoder%2FBuyer-Lead-Intake/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Megatron-XCoder%2FBuyer-Lead-Intake/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Megatron-XCoder","download_url":"https://codeload.github.com/Megatron-XCoder/Buyer-Lead-Intake/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Megatron-XCoder%2FBuyer-Lead-Intake/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000960,"owners_count":26082973,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-10-09T07:27:56.670Z","updated_at":"2025-10-09T07:28:05.655Z","avatar_url":"https://github.com/Megatron-XCoder.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Buyer Lead Intake System\n\nA comprehensive web application built with Next.js for capturing, managing, and tracking real estate buyer leads. This system provides a complete solution for real estate businesses to manage their lead pipeline efficiently.\n\n**🚀 Ready for Production - All deployment issues resolved!**\n\n## 📋 Table of Contents\n\n- [Features](#features)\n- [Technology Stack](#technology-stack)\n- [Local Setup](#local-setup)\n- [Design Choices](#design-choices)\n- [API Endpoints](#api-endpoints)\n- [Features Implemented](#features-implemented)\n- [Testing](#testing)\n- [Project Structure](#project-structure)\n\n## ✨ Features\n\n### Core Functionality\n- **Lead Management**: Create, view, edit, and track buyer leads\n- **Advanced Search \u0026 Filtering**: Search by name, phone, email with filters for city, property type, status, and timeline\n- **Server-Side Pagination**: Efficient data loading with 10 leads per page\n- **CSV Import/Export**: Bulk import leads and export filtered data\n- **Change Tracking**: Complete audit trail of all lead modifications\n- **Concurrency Control**: Prevents data loss from simultaneous edits\n\n### User Experience\n- **Responsive Design**: Works seamlessly on desktop and mobile devices\n- **Real-time Validation**: Client-side and server-side validation with immediate feedback\n- **Error Handling**: Global error boundary and user-friendly error messages\n- **Rate Limiting**: Prevents abuse with configurable limits\n- **Demo Authentication**: Simple login system for demonstration\n\n## 🛠 Technology Stack\n\n- **Framework**: Next.js 15 with App Router and TypeScript\n- **Database**: SQLite with Prisma ORM\n- **Validation**: Zod for schema validation\n- **Authentication**: NextAuth.js with demo login\n- **Styling**: Tailwind CSS with responsive design\n- **Forms**: React Hook Form with Zod resolver\n- **Icons**: Lucide React\n- **Notifications**: Sonner for toast messages\n- **Testing**: Jest with Testing Library\n- **Rate Limiting**: rate-limiter-flexible\n\n## 🚀 Local Setup\n\n### Prerequisites\n- Node.js 18+ installed\n- npm or yarn package manager\n\n### Installation Steps\n\n1. **Clone the repository**\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd buyer-lead-intake\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Set up environment variables**\n   Create a `.env` file in the root directory:\n   ```env\n   DATABASE_URL=\"file:./dev.db\"\n   NEXTAUTH_URL=\"http://localhost:3000\"\n   NEXTAUTH_SECRET=\"your-development-secret-key-change-in-production\"\n   ```\n\n4. **Initialize the database**\n   ```bash\n   npx prisma migrate dev --name init\n   npx prisma generate\n   ```\n\n5. **Start the development server**\n   ```bash\n   npm run dev\n   ```\n\n6. **Access the application**\n   Open [http://localhost:3000](http://localhost:3000) in your browser (or the port shown in terminal if 3000 is occupied)\n\n### First Time Setup\n1. Click \"Log in as Demo User\" on the sign-in page\n2. You'll be redirected to the dashboard\n3. Start creating leads or import sample data\n\n## 🏗 Design Choices\n\n### Architecture Decisions\n\n**1. Next.js App Router**\n- Chosen for its file-based routing, server components, and excellent developer experience\n- Server-side rendering ensures fast initial page loads and better SEO\n- API routes provide a clean backend structure\n\n**2. Prisma with SQLite**\n- Prisma offers excellent TypeScript integration and migration management\n- SQLite chosen for simplicity and portability in development\n- Easy to migrate to PostgreSQL/MySQL for production\n\n**3. Validation Strategy**\n- Shared Zod schema between client and server ensures consistency\n- Real-time client validation provides immediate feedback\n- Server-side validation acts as the authoritative source of truth\n- Conditional validation (BHK required for apartments/villas) implemented as custom refinements\n\n**4. Authentication**\n- NextAuth.js provides a robust, production-ready authentication system\n- Demo login simplifies testing while maintaining security patterns\n- Session-based authentication with JWT tokens\n\n**5. State Management**\n- Server-side rendering eliminates need for complex client state\n- URL-based state for filters and pagination ensures shareable URLs\n- React Hook Form for efficient form state management\n\n### Database Design\n\n**Buyer Model**: Core entity with comprehensive lead information\n- UUID primary keys for better scalability\n- Indexed fields for common queries (status, city, propertyType)\n- Flexible budget fields (optional min/max)\n- Tags stored as comma-separated strings for simplicity\n\n**BuyerHistory Model**: Audit trail for all changes\n- JSON diff storage for flexibility\n- User tracking for accountability\n- Cascading deletes maintain referential integrity\n\n**User Model**: Simple user management\n- Supports future expansion (roles, permissions)\n- Linked to lead ownership and change tracking\n\n### Performance Optimizations\n\n**1. Database Queries**\n- Strategic indexing on frequently queried fields\n- Pagination to limit data transfer\n- Efficient search using database-level text search\n\n**2. Rate Limiting**\n- Protects against abuse and ensures fair usage\n- Different limits for regular operations vs. bulk imports\n- Memory-based for simplicity (can be upgraded to Redis)\n\n**3. Concurrent Access**\n- Optimistic concurrency control prevents lost updates\n- User-friendly error messages when conflicts occur\n- Automatic refresh suggested for latest data\n\n## 📡 API Endpoints\n\n### Buyers\n- `GET /api/buyers` - List buyers with pagination and filtering\n- `POST /api/buyers` - Create new buyer\n- `PUT /api/buyers/[id]` - Update existing buyer\n- `GET /api/buyers/export` - Export filtered buyers as CSV\n- `POST /api/buyers/import` - Import buyers from CSV\n\n### Authentication\n- `GET/POST /api/auth/[...nextauth]` - NextAuth.js authentication endpoints\n\n## ✅ Features Implemented\n\n### ✅ Core Requirements\n- [x] **Project Setup**: Next.js with TypeScript, Prisma, and SQLite\n- [x] **Data Models**: Buyer and BuyerHistory with proper relationships\n- [x] **Validation**: Zod schemas with conditional validation\n- [x] **Authentication**: Demo login system with NextAuth.js\n\n### ✅ Pages and Functionality\n- [x] **Create Lead Page** (`/buyers/new`)\n  - [x] Comprehensive form with all required fields\n  - [x] Conditional BHK field for apartments/villas\n  - [x] Real-time client-side validation\n  - [x] Server-side validation with error handling\n\n- [x] **List \u0026 Search Page** (`/buyers`)\n  - [x] Server-side rendering for performance\n  - [x] Pagination (10 leads per page)\n  - [x] Advanced filtering (city, property type, status, timeline)\n  - [x] Debounced search across multiple fields\n  - [x] URL-synced state for shareable filters\n\n- [x] **View \u0026 Edit Page** (`/buyers/[id]`)\n  - [x] Detailed view of all lead information\n  - [x] In-place editing with same validation rules\n  - [x] Concurrency control with conflict detection\n  - [x] Change history display (last 5 changes)\n\n### ✅ CSV Import/Export\n- [x] **CSV Export**\n  - [x] Respects current filters and search\n  - [x] Comprehensive data export with timestamps\n  - [x] Proper CSV formatting and headers\n\n- [x] **CSV Import** (`/buyers/import`)\n  - [x] File upload with validation\n  - [x] Batch processing (max 200 rows)\n  - [x] Detailed error reporting per row\n  - [x] Transactional imports (all or nothing)\n  - [x] Template download for proper formatting\n\n### ✅ Quality Requirements\n- [x] **Authorization**: Owner-based access control for editing\n- [x] **Rate Limiting**: API protection against abuse\n- [x] **Error Handling**: Global error boundary and user-friendly messages\n- [x] **Unit Tests**: Validation logic testing with Jest\n- [x] **Accessibility**: Proper labels and keyboard navigation\n- [x] **Empty States**: Helpful messages when no data found\n\n### ✅ Additional Features\n- [x] **Dashboard**: Statistics and recent leads overview\n- [x] **Responsive Design**: Mobile-friendly interface\n- [x] **Real-time Feedback**: Toast notifications for user actions\n- [x] **Status Indicators**: Color-coded status badges\n- [x] **Navigation**: Clean, intuitive navigation structure\n\n## 🧪 Testing\n\n### Running Tests\n```bash\n# Run all tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n### Test Coverage\n- **Validation Logic**: Comprehensive tests for Zod schemas\n- **Business Rules**: Budget validation and conditional requirements\n- **Edge Cases**: Phone number formats and enum validations\n\n### Test Structure\n- **Unit Tests**: Focus on validation and business logic\n- **Integration Tests**: API endpoints (can be added)\n- **E2E Tests**: User workflows (can be added with Playwright)\n\n## 📁 Project Structure\n\n```\nbuyer-lead-intake/\n├── app/                          # Next.js App Router\n│   ├── api/                      # API routes\n│   │   ├── auth/                 # Authentication endpoints\n│   │   └── buyers/               # Buyer CRUD and import/export\n│   ├── buyers/                   # Buyer-related pages\n│   │   ├── new/                  # Create new lead\n│   │   ├── import/               # CSV import page\n│   │   └── [id]/                 # View/edit specific lead\n│   ├── auth/                     # Authentication pages\n│   ├── globals.css               # Global styles\n│   ├── layout.tsx                # Root layout\n│   ├── page.tsx                  # Dashboard/home page\n│   ├── error.tsx                 # Global error boundary\n│   └── not-found.tsx             # 404 page\n├── components/                   # Reusable components\n│   ├── navigation.tsx            # Main navigation\n│   ├── buyer-filters.tsx         # Search and filter controls\n│   ├── pagination.tsx            # Pagination component\n│   ├── export-button.tsx         # CSV export functionality\n│   ├── buyer-edit-form.tsx       # Lead editing form\n│   └── buyer-history.tsx         # Change history display\n├── lib/                          # Utility libraries\n│   ├── validations/              # Zod schemas\n│   ├── db.ts                     # Prisma client\n│   ├── rate-limiter.ts           # Rate limiting configuration\n│   └── types.ts                  # TypeScript type definitions\n├── prisma/                       # Database schema and migrations\n│   ├── schema.prisma             # Database schema\n│   └── migrations/               # Migration files\n├── __tests__/                    # Test files\n│   └── validation.test.ts        # Validation logic tests\n├── types/                        # Global type definitions\n└── Configuration files           # Next.js, Tailwind, Jest, etc.\n```\n\n## 🚀 Production Deployment\n\n### Environment Variables\nUpdate `.env` for production:\n```env\nDATABASE_URL=\"your-production-database-url\"\nNEXTAUTH_URL=\"https://your-domain.com\"\nNEXTAUTH_SECRET=\"strong-production-secret\"\n```\n\n### Database Migration\nFor production databases (PostgreSQL/MySQL):\n1. Update `prisma/schema.prisma` datasource\n2. Run `npx prisma migrate deploy`\n3. Run `npx prisma generate`\n\n### Performance Considerations\n- Enable Redis for rate limiting in production\n- Configure proper database connection pooling\n- Set up monitoring and logging\n- Implement proper backup strategies\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the ISC License - see the package.json file for details.\n\n---\n\n**Built with ❤️ using Next.js, TypeScript, and modern web technologies.**# Deployment Ready Tue, Sep 16, 2025  2:19:05 PM\n# Trigger Render redeploy\n# Updated database configuration for Render deployment\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegatron-xcoder%2Fbuyer-lead-intake","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmegatron-xcoder%2Fbuyer-lead-intake","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegatron-xcoder%2Fbuyer-lead-intake/lists"}