{"id":31592615,"url":"https://github.com/nadimtuhin/hexagonal-phonebook","last_synced_at":"2026-05-07T05:39:40.446Z","repository":{"id":305599932,"uuid":"1023303972","full_name":"nadimtuhin/hexagonal-phonebook","owner":"nadimtuhin","description":"Next.js phonebook with hexagonal architecture - Clean separation of business logic with SQLite, MySQL \u0026 LocalStorage adapters","archived":false,"fork":false,"pushed_at":"2025-07-21T02:30:32.000Z","size":141,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T03:24:13.303Z","etag":null,"topics":["clean-architecture","hexagonal-architecture","mysql","nextjs","phonebook","ports-and-adapters","sqlite","typescript"],"latest_commit_sha":null,"homepage":"","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/nadimtuhin.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}},"created_at":"2025-07-21T00:34:41.000Z","updated_at":"2025-07-21T02:30:36.000Z","dependencies_parsed_at":"2025-07-21T03:24:44.433Z","dependency_job_id":"7e417ff0-edd0-47a2-8ecc-906db43177dc","html_url":"https://github.com/nadimtuhin/hexagonal-phonebook","commit_stats":null,"previous_names":["nadimtuhin/hexagonal-phonebook"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nadimtuhin/hexagonal-phonebook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Fhexagonal-phonebook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Fhexagonal-phonebook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Fhexagonal-phonebook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Fhexagonal-phonebook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nadimtuhin","download_url":"https://codeload.github.com/nadimtuhin/hexagonal-phonebook/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Fhexagonal-phonebook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32725214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["clean-architecture","hexagonal-architecture","mysql","nextjs","phonebook","ports-and-adapters","sqlite","typescript"],"created_at":"2025-10-06T03:11:38.444Z","updated_at":"2026-05-07T05:39:40.441Z","avatar_url":"https://github.com/nadimtuhin.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hexagonal Architecture Phonebook\n\nA Next.js phonebook application built with hexagonal architecture (ports and adapters pattern) supporting multiple storage backends.\n\n## Features\n\n- **Hexagonal Architecture**: Clean separation of business logic from infrastructure\n- **Multiple Storage Adapters**: SQLite, LocalStorage, and MySQL support\n- **TypeScript**: Full type safety across the application\n- **Next.js 14**: Modern React framework with App Router\n- **Tailwind CSS**: Utility-first CSS framework for styling\n\n## Architecture Overview\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    Presentation Layer                        │\n│              (Next.js Pages \u0026 Components)                    │\n└─────────────────────┬───────────────────────────────────────┘\n                      │\n┌─────────────────────▼───────────────────────────────────────┐\n│                   Application Layer                          │\n│                  (Use Cases/Services)                        │\n└─────────────────────┬───────────────────────────────────────┘\n                      │\n┌─────────────────────▼───────────────────────────────────────┐\n│                    Domain Layer                              │\n│              (Entities \u0026 Business Rules)                     │\n└─────────────────────┬───────────────────────────────────────┘\n                      │\n┌─────────────────────▼───────────────────────────────────────┐\n│                 Infrastructure Layer                         │\n│     ┌──────────┬──────────────┬────────────────┐           │\n│     │ SQLite   │ LocalStorage │     MySQL      │           │\n│     │ Adapter  │   Adapter    │    Adapter     │           │\n│     └──────────┴──────────────┴────────────────┘           │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 18+ \n- npm or yarn\n- Docker (for MySQL adapter)\n\n### Installation\n\n1. Clone the repository\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Copy the environment variables:\n   ```bash\n   cp .env.example .env.local\n   ```\n\n4. Configure your preferred database adapter in `.env.local`\n\n### Running the Application\n\nDevelopment mode:\n```bash\nnpm run dev\n```\n\nProduction build:\n```bash\nnpm run build\nnpm run start\n```\n\n## Database Configuration\n\n### SQLite (Default)\n\nNo additional setup required. The database file will be created automatically.\n\n```env\nDB_ADAPTER=sqlite\nSQLITE_PATH=./phonebook.db\n```\n\n### LocalStorage\n\nWorks only in the browser. Data persists in browser storage.\n\n```env\nDB_ADAPTER=localstorage\n```\n\n### MySQL\n\n1. Start MySQL using Docker:\n   ```bash\n   cd docker\n   docker-compose up -d\n   ```\n\n2. Configure environment:\n   ```env\n   DB_ADAPTER=mysql\n   MYSQL_HOST=localhost\n   MYSQL_PORT=3306\n   MYSQL_USER=phonebook_user\n   MYSQL_PASSWORD=phonebook_pass\n   MYSQL_DATABASE=phonebook\n   ```\n\n## API Endpoints\n\n- `GET /api/contacts` - List all contacts (supports `?q=search` query)\n- `POST /api/contacts` - Create a new contact\n- `GET /api/contacts/[id]` - Get a specific contact\n- `PUT /api/contacts/[id]` - Update a contact\n- `DELETE /api/contacts/[id]` - Delete a contact\n\n## Project Structure\n\n```\nsrc/\n├── domain/               # Core business logic\n│   ├── entities/        # Domain models\n│   ├── repositories/    # Repository interfaces (ports)\n│   └── value-objects/   # Value objects\n├── application/         # Application services\n│   ├── use-cases/      # Business use cases\n│   └── services/       # Application services\n├── infrastructure/      # External adapters\n│   ├── adapters/       # Database implementations\n│   ├── config/         # Configuration\n│   └── factories/      # Factory patterns\n├── presentation/        # UI components\n│   └── components/     # React components\n└── app/                # Next.js app router\n    ├── api/           # API routes\n    └── page.tsx       # Main page\n```\n\n## Testing\n\nThe application follows hexagonal architecture principles, making it easy to test business logic independently of infrastructure concerns.\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnadimtuhin%2Fhexagonal-phonebook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnadimtuhin%2Fhexagonal-phonebook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnadimtuhin%2Fhexagonal-phonebook/lists"}