{"id":28312141,"url":"https://github.com/kenzycodex/short.ly","last_synced_at":"2026-01-24T08:31:24.560Z","repository":{"id":292620869,"uuid":"981445457","full_name":"kenzycodex/Short.ly","owner":"kenzycodex","description":"Short.ly - Enterprise Cloud-Based URL Shortener Platform","archived":false,"fork":false,"pushed_at":"2025-05-11T22:52:25.000Z","size":97,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-23T11:45:35.226Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kenzycodex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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-05-11T05:50:42.000Z","updated_at":"2025-05-11T22:52:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"48591749-105b-480f-bc46-4a7c1b5705f9","html_url":"https://github.com/kenzycodex/Short.ly","commit_stats":null,"previous_names":["kenzycodex/short.ly"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kenzycodex/Short.ly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2FShort.ly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2FShort.ly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2FShort.ly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2FShort.ly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kenzycodex","download_url":"https://codeload.github.com/kenzycodex/Short.ly/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kenzycodex%2FShort.ly/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28720740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T08:27:05.734Z","status":"ssl_error","status_checked_at":"2026-01-24T08:27:01.197Z","response_time":89,"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":[],"created_at":"2025-05-24T16:20:39.093Z","updated_at":"2026-01-24T08:31:24.554Z","avatar_url":"https://github.com/kenzycodex.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Short.ly - Enterprise URL Shortener Platform\n\n\u003cdiv align=\"center\"\u003e\n\n\u003c!-- ![Short.ly Logo](https://via.placeholder.com/200x60?text=Short.ly) --\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D%2016.0.0-brightgreen)](package.json)\n[![MongoDB](https://img.shields.io/badge/MongoDB-4.4%2B-green)](https://www.mongodb.com/)\n[![Redis](https://img.shields.io/badge/Redis-6.0%2B-red)](https://redis.io/)\n[![Docker](https://img.shields.io/badge/Docker-ready-blue)](docker/docker-compose.yml)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n*A professional, production-ready cloud URL shortener platform with analytics, caching, and multi-cloud deployment capabilities.*\n\n\u003c/div\u003e\n\n## 📋 Table of Contents\n\n- [Features](#-features)\n- [Architecture](#-architecture)\n- [Tech Stack](#-tech-stack)\n- [Installation](#-installation)\n- [Configuration](#-configuration)\n- [API Documentation](#-api-documentation)\n- [Cloud Deployment](#-cloud-deployment)\n- [Monitoring](#-monitoring)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## ✨ Features\n\n### Core Features\n- **URL Shortening**\n  - Custom aliases support\n  - Expiration dates\n  - Batch URL creation\n  - URL deactivation/reactivation\n \n### Analytics\n- **Comprehensive Tracking**\n  - Click counts and history\n  - Referrer analysis\n  - Browser/device detection\n  - Geographic location tracking\n  - Time-series visualizations\n\n### Performance\n- **Advanced Caching**\n  - Redis-based for optimal performance\n  - Tiered caching strategy\n  - Cache invalidation on URL updates\n  - Distributed cache support\n\n### Security\n- **Enterprise-Grade Security**\n  - Rate limiting\n  - Input validation\n  - JWT authentication\n  - CSRF protection\n  - XSS prevention\n\n### Integrations\n- **Serverless Architecture Support**\n  - AWS Lambda integration\n  - Cloudflare Workers compatible\n  - Google Cloud Functions support\n  \n### Developer Experience\n- **Multi-Environment Support**\n  - Development mode\n  - MVP mode\n  - Production mode\n  - Seamless environment switching\n\n## 🏗 Architecture\n\nShort.ly is built using Clean Architecture principles, ensuring separation of concerns and allowing for easy maintenance and extensibility.\n\n![Architecture Diagram](https://via.placeholder.com/800x400?text=Short.ly+Architecture)\n\n### Core Layers\n\n#### 1. Domain Layer\nThe inner-most layer containing business entities and logic independent of any external frameworks or technologies.\n\n- **Entities**: `Url`, `Analytics`, etc.\n- **Use Cases**: Business rules defining how entities interact.\n- **Interfaces**: Contracts that external layers must implement.\n\n#### 2. Infrastructure Layer\nImplements interfaces defined by the domain layer and handles external dependencies.\n\n- **Database Adapters**: MongoDB implementation of repositories.\n- **Cache Adapters**: Redis implementation of cache repositories.\n- **External Services**: Third-party API integrations (IP geolocation, etc.).\n\n#### 3. Presentation Layer\nHandles HTTP requests and responses, implementing the API endpoints.\n\n- **Controllers**: Handle incoming requests and format responses.\n- **Routes**: Define API endpoints and connect to controllers.\n- **Middlewares**: Authentication, rate limiting, error handling, etc.\n\n#### 4. Application Layer\nCoordinates the flow of data and orchestrates use cases.\n\n- **Services**: Coordinate multiple use cases and aggregate data.\n- **DTOs**: Data Transfer Objects for transforming data between layers.\n\n### Directory Structure\n\n```\n/short.ly\n├── src/\n│   ├── core/                         # Domain Layer\n│   │   ├── entities/\n│   │   ├── interfaces/\n│   │   └── use-cases/\n│   │\n│   ├── infrastructure/               # Infrastructure Layer\n│   │   ├── db/\n│   │   ├── cache/\n│   │   └── providers/\n│   │\n│   ├── presentation/                 # Presentation Layer\n│   │   ├── controllers/\n│   │   ├── middlewares/\n│   │   ├── routes/\n│   │   └── validators/\n│   │\n│   ├── services/                     # Application Layer\n│   │   ├── shortenerService.js\n│   │   └── analyticsService.js\n│   │\n│   ├── config/                       # Configuration\n│   │   ├── index.js\n│   │   └── env.js\n│   │\n│   ├── utils/                        # Utilities\n│   ├── main.js                       # Entry point\n│   └── server.js                     # Express server\n│\n├── lambda/                           # AWS Lambda Functions\n├── scripts/                          # Deployment Scripts\n├── docker/                           # Docker Configuration\n├── tests/                            # Test Suites\n└── docs/                             # Documentation\n```\n\n## 🛠 Tech Stack\n\n### Backend\n- **[Node.js](https://nodejs.org/)** (v16+): JavaScript runtime\n- **[Express](https://expressjs.com/)**: Web framework\n- **[MongoDB](https://www.mongodb.com/)**: NoSQL database for persistence\n- **[Redis](https://redis.io/)**: In-memory data structure store for caching\n\n### Storage\n- **MongoDB Atlas**: For production database hosting\n- **Redis Cloud/ElastiCache**: For production cache hosting\n\n### Hosting/Cloud\n- **AWS**: Lambda, EC2, Route 53, S3\n- **Google Cloud Platform**: Cloud Run, Cloud Functions, Cloud Storage\n- **Cloudflare**: Workers, DNS, caching\n\n### Monitoring \u0026 Logging\n- **Winston**: Logging library\n- **Express Prometheus**: Metrics collection\n- **Morgan**: HTTP request logging\n\n### Development\n- **Docker**: Containerization\n- **Jest**: Testing framework\n- **ESLint**: Code linting\n- **Prettier**: Code formatting\n- **Husky**: Git hooks\n\n## 📥 Installation\n\n### Prerequisites\n- Node.js (v16 or higher)\n- MongoDB (v4.4 or higher)\n- Redis (v6.0 or higher)\n- Docker and Docker Compose (optional, for containerized development)\n\n### Local Setup\n\n1. **Clone the repository**\n\n```bash\ngit clone https://github.com/kenzycodex/short.ly.git\ncd short.ly\n```\n\n2. **Install dependencies**\n\n```bash\nnpm install\n```\n\n3. **Set up environment variables**\n\n```bash\n# For development\ncp .env.dev .env\n```\n\n4. **Start with Docker Compose** (recommended)\n\n```bash\ndocker-compose -f docker/docker-compose.yml up -d\n```\n\n5. **Or start services individually**\n\n```bash\n# Start MongoDB\nmongod --dbpath /path/to/data/db\n\n# Start Redis\nredis-server\n\n# Start the application\nnpm run dev\n```\n\n6. **Verify installation**\n\nVisit [http://localhost:3000/api-docs](http://localhost:3000/api-docs) to view the API documentation and [http://localhost:3000/api/v1/health](http://localhost:3000/api/v1/health) to check the application health.\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run specific test suite\nnpm test -- --testPathPattern=url\n\n# Run with coverage\nnpm test -- --coverage\n```\n\n## ⚙️ Configuration\n\nShort.ly supports multiple environments through different configuration files:\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `APP_ENV` | Environment (development, mvp, production) | `development` |\n| `PORT` | Port the server listens on | `3000` |\n| `MONGO_URI` | MongoDB connection string | `mongodb://localhost:27017/shortlydb_dev` |\n| `REDIS_HOST` | Redis host | `localhost` |\n| `REDIS_PORT` | Redis port | `6379` |\n| `URL_LENGTH` | Length of generated short codes | `7` |\n| `DOMAIN_URL` | Domain for short URLs | `http://localhost:3000` |\n| `ANALYTICS_ENABLED` | Whether analytics are enabled | `true` |\n| `USE_LAMBDA_REDIRECTS` | Use AWS Lambda for redirects | `false` |\n\n### Environment-Specific Configuration\n\n- `.env.dev`: Development environment settings\n- `.env.mvp`: Minimum Viable Product environment settings\n- `.env.prod`: Production environment settings\n\n### Switching Environments\n\n```bash\n# Development mode\ncp .env.dev .env\nnpm run dev\n\n# MVP mode\ncp .env.mvp .env\nnpm run start:mvp\n\n# Production mode\ncp .env.prod .env\nnpm run start:prod\n```\n\n### Advanced Configuration\n\nFor advanced configuration options, see the [Configuration Guide](docs/CONFIGURATION.md).\n\n## 📚 API Documentation\n\n### Core Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/api/v1/urls` | Create a new short URL |\n| `GET` | `/api/v1/urls/{shortCode}` | Get URL details |\n| `PATCH` | `/api/v1/urls/{shortCode}` | Update a URL |\n| `DELETE` | `/api/v1/urls/{shortCode}` | Delete a URL |\n| `GET` | `/{shortCode}` | Redirect to the original URL |\n| `GET` | `/api/v1/analytics/{shortCode}` | Get URL analytics |\n\n### Swagger Documentation\n\nWhen the application is running, Swagger documentation is available at:\n\n- Development: [http://localhost:3000/api-docs](http://localhost:3000/api-docs)\n- MVP: [https://api-mvp.short.ly/api-docs](https://api-mvp.short.ly/api-docs)\n- Production: [https://api.short.ly/api-docs](https://api.short.ly/api-docs)\n\n### Detailed API Documentation\n\nFor detailed API documentation, see the [API Guide](docs/API.md).\n\n## 🌩 Cloud Deployment\n\nShort.ly can be deployed to various cloud providers:\n\n### AWS Deployment\n\n1. **Set up infrastructure**\n\n```bash\n# Create Lambda function for redirects\n./scripts/deploy-lambda.sh -e prod -r us-east-1\n\n# Deploy to EC2 or ECS\n./scripts/deploy.sh -e prod\n```\n\n2. **Configure DNS with Route 53**\n\n```bash\n# Create DNS records\naws route53 change-resource-record-sets --hosted-zone-id ZXXXXXXXXXX --change-batch file://route53-changes.json\n```\n\nFor a step-by-step AWS deployment guide, see [AWS Deployment](docs/deployment/AWS.md).\n\n### Google Cloud Deployment\n\n1. **Build and push Docker image**\n\n```bash\ndocker build -t gcr.io/your-project/short-ly .\ndocker push gcr.io/your-project/short-ly\n```\n\n2. **Deploy to Cloud Run**\n\n```bash\ngcloud run deploy short-ly --image gcr.io/your-project/short-ly --platform managed --region us-central1\n```\n\nFor a step-by-step GCP deployment guide, see [GCP Deployment](docs/deployment/GCP.md).\n\n### CI/CD Pipeline\n\nShort.ly includes GitHub Actions workflows for CI/CD:\n\n- `.github/workflows/test.yml`: Runs tests on pull requests\n- `.github/workflows/deploy.yml`: Deploys to appropriate environment on merge to main\n\nFor CI/CD details, see [CI/CD Documentation](docs/CI_CD.md).\n\n## 📊 Monitoring\n\n### Health Checks\n\nThe application includes a health check endpoint at `/api/v1/health` that returns the status of the application and its dependencies.\n\n### Metrics\n\nShort.ly exports Prometheus metrics at `/api/v1/metrics` for monitoring:\n\n- Request counts and latencies\n- Redis cache hit/miss ratios\n- MongoDB query performance\n- Memory usage\n\n### Logging\n\nLogs are structured as JSON for easy parsing and analysis:\n\n```javascript\n{\n  \"level\": \"info\",\n  \"timestamp\": \"2023-07-22T10:15:30.123Z\",\n  \"message\": \"URL created\",\n  \"shortCode\": \"abc123\",\n  \"originalUrl\": \"https://example.com\"\n}\n```\n\nFor production deployments, logs can be shipped to:\n- AWS CloudWatch\n- Google Cloud Logging\n- ELK Stack\n- Datadog\n\nFor detailed monitoring setup, see [Monitoring Guide](docs/MONITORING.md).\n\n## 🤝 Contributing\n\nWe welcome contributions to Short.ly! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on:\n\n- Code of conduct\n- Development process\n- Pull request process\n- Coding standards\n- Testing requirements\n\n### Getting Started with Contributing\n\n1. Fork the repository\n2. Create your feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add some 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 MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgements\n\n- [Express.js](https://expressjs.com/) - Web framework\n- [MongoDB](https://www.mongodb.com/) - Database\n- [Redis](https://redis.io/) - Caching\n- [AWS Lambda](https://aws.amazon.com/lambda/) - Serverless computing\n- [Docker](https://www.docker.com/) - Containerization\n- [Swagger](https://swagger.io/) - API documentation\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[Website](https://short.ly)** • \n**[Documentation](https://docs.short.ly)** • \n**[Issues](https://github.com/kenzycodex/short.ly/issues)** • \n**[Support](support@short.ly)**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenzycodex%2Fshort.ly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkenzycodex%2Fshort.ly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkenzycodex%2Fshort.ly/lists"}