{"id":34674668,"url":"https://github.com/u-leslie/skitt_be","last_synced_at":"2025-12-24T20:02:26.290Z","repository":{"id":328320058,"uuid":"1111366214","full_name":"u-leslie/skitt_be","owner":"u-leslie","description":"Skitt Backend","archived":false,"fork":false,"pushed_at":"2025-12-12T10:35:25.000Z","size":74,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-13T23:18:15.891Z","etag":null,"topics":["aws-ec2","node","openapi","postgres","rds-postgres","zod-validation"],"latest_commit_sha":null,"homepage":"http://13.60.16.21:3001/api-docs","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/u-leslie.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-06T19:46:21.000Z","updated_at":"2025-12-13T10:36:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/u-leslie/skitt_be","commit_stats":null,"previous_names":["u-leslie/skitt_be"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/u-leslie/skitt_be","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-leslie%2Fskitt_be","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-leslie%2Fskitt_be/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-leslie%2Fskitt_be/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-leslie%2Fskitt_be/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/u-leslie","download_url":"https://codeload.github.com/u-leslie/skitt_be/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u-leslie%2Fskitt_be/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28007456,"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-12-24T02:00:07.193Z","response_time":83,"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":["aws-ec2","node","openapi","postgres","rds-postgres","zod-validation"],"created_at":"2025-12-24T20:01:12.514Z","updated_at":"2025-12-24T20:02:26.284Z","avatar_url":"https://github.com/u-leslie.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Skitt Backend - Feature Flags \u0026 Experiment Platform\n\nA robust Node.js/TypeScript backend API for managing feature flags, user targeting, and A/B experiments with comprehensive metrics and analytics.\n\n## 🚀 Features\n\n- **Feature Flag Management**: Create, update, and manage feature flags\n- **User Targeting**: Enable/disable features for specific users\n- **Experiment Management**: Create and manage A/B tests with variant distribution\n- **Metrics \u0026 Analytics**: Track flag usage, events, and dashboard metrics\n- **RESTful API**: Clean, well-documented REST endpoints\n- **API Documentation**: Interactive Swagger/OpenAPI documentation\n- **Type Safety**: Full TypeScript support with Zod validation\n- **PostgreSQL**: Robust relational database with proper schema design\n\n## 🛠 Tech Stack\n\n- **Runtime**: Node.js\n- **Framework**: Express.js\n- **Language**: TypeScript\n- **Database**: PostgreSQL\n- **Validation**: Zod\n- **API Documentation**: Swagger/OpenAPI (swagger-jsdoc, swagger-ui-express)\n- **Architecture**: Service-oriented with separation of concerns\n\n## 📋 Prerequisites\n\n- Node.js (v18 or higher)\n- PostgreSQL (v12 or higher)\n- npm or yarn\n\n## 🔧 Installation\n\n1. **Clone the repository** (if not already done)\n   ```bash\n   cd backend\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Set up environment variables**\n   ```bash\n   cp .env.example .env\n   ```\n   \n   Edit `.env` with your configuration:\n   ```env\n   PORT=3001\n   NODE_ENV=development\n   \n   # PostgreSQL Configuration\n   DB_HOST=localhost\n   DB_PORT=5432\n   DB_NAME=skitt\n   DB_USER=postgres\n   DB_PASSWORD=postgres\n   ```\n\n4. **Create PostgreSQL database**\n   ```bash\n   # Connect to PostgreSQL\n   psql -U postgres\n   \n   # Create database\n   CREATE DATABASE skitt;\n   \n   # Exit psql\n   \\q\n   ```\n\n5. **Start the server**\n   ```bash\n   npm run dev\n   ```\n\n   The server will automatically:\n   - Initialize the database schema\n   - Start on the configured port (default: 3001)\n   - Set up Swagger documentation at `http://localhost:3001/api-docs`\n\n## 📁 Project Structure\n\n```\nbackend/\n├── src/\n│   ├── config/          # Configuration files (Swagger, etc.)\n│   ├── database/        # Database connection and initialization\n│   ├── middleware/       # Express middleware (error handling, async)\n│   ├── models/          # Database models/data access layer\n│   ├── routes/          # API route definitions (endpoints only)\n│   ├── schemas/         # Zod validation schemas\n│   ├── services/        # Business logic layer\n│   └── index.ts        # Application entry point\n├── .env.example        # Environment variables template\n├── .gitignore          # Git ignore rules\n├── package.json        # Dependencies and scripts\n├── tsconfig.json       # TypeScript configuration\n└── README.md          # This file\n```\n\n## 🏗 Architecture\n\nThe backend follows a clean architecture pattern with clear separation of concerns:\n\n- **Routes**: Handle HTTP requests/responses only, delegate to services\n- **Services**: Contain all business logic and validation\n- **Models**: Data access layer (database queries)\n- **Schemas**: Input validation using Zod\n- **Middleware**: Error handling and async wrapper\n\n### Request Flow\n\n```\nRequest → Route → Service → Model → Database\n                ↓\n         Validation (Zod)\n                ↓\n         Error Handling\n```\n\n## 📡 API Endpoints\n\n### Feature Flags\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/flags` | Get all feature flags |\n| GET | `/api/flags/:id` | Get feature flag by ID |\n| POST | `/api/flags` | Create a new feature flag |\n| PUT | `/api/flags/:id` | Update a feature flag |\n| DELETE | `/api/flags/:id` | Delete a feature flag |\n\n### Users\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/users` | Get all users |\n| GET | `/api/users/:id` | Get user by ID |\n| POST | `/api/users` | Create a new user |\n| PUT | `/api/users/:id` | Update a user |\n| DELETE | `/api/users/:id` | Delete a user |\n| GET | `/api/users/:userId/flags` | Get flags assigned to a user |\n| POST | `/api/users/:userId/flags/:flagId` | Assign flag to user |\n| DELETE | `/api/users/:userId/flags/:flagId` | Remove flag from user |\n\n### Experiments\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/experiments` | Get all experiments |\n| GET | `/api/experiments/:id` | Get experiment by ID |\n| GET | `/api/experiments/flag/:flagId` | Get experiments by flag ID |\n| POST | `/api/experiments` | Create a new experiment |\n| PUT | `/api/experiments/:id` | Update an experiment |\n| DELETE | `/api/experiments/:id` | Delete an experiment |\n\n### Metrics\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/metrics/events` | Track a flag event |\n| GET | `/api/metrics` | Get metrics for all flags |\n| GET | `/api/metrics/flags/:flagId` | Get metrics for a specific flag |\n| GET | `/api/metrics/dashboard` | Get dashboard summary |\n\n### Health Check\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/health` | Health check endpoint |\n\n## 📚 API Documentation\n\nInteractive API documentation is available via Swagger UI:\n\n**URL**: `http://localhost:3001/api-docs`\n\nThe Swagger UI provides:\n- Complete API endpoint documentation\n- Request/response schemas\n- Try-it-out functionality\n- Example requests and responses\n\n## 💻 Development\n\n### Available Scripts\n\n```bash\n# Development mode with hot reload\nnpm run dev\n\n# Build TypeScript to JavaScript\nnpm run build\n\n# Run production build\nnpm start\n\n# Type checking without building\nnpm run type-check\n```\n\n### Code Style\n\n- Use TypeScript for all code\n- Follow the existing architecture pattern\n- Keep routes thin (endpoints only)\n- Put all logic in services\n- Use Zod schemas for validation\n- Handle errors using AppError class\n\n### Adding New Endpoints\n\n1. **Create/Update Schema** in `src/schemas/`\n2. **Add Service Method** in `src/services/`\n3. **Add Route** in `src/routes/`\n4. **Add Swagger Documentation** in route file\n5. **Update Swagger Config** if needed in `src/config/swagger.ts`\n\n## 🗄 Database Schema\n\n### Tables\n\n- **feature_flags**: Core feature flag definitions\n- **users**: User information and attributes\n- **user_flag_assignments**: User-specific flag overrides\n- **experiments**: A/B test configurations\n- **experiment_assignments**: User experiment assignments\n- **flag_events**: Event tracking for analytics\n\nThe database schema is automatically initialized on server start.\n\n## 🔒 Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | Server port | `3001` |\n| `NODE_ENV` | Environment (development/production) | `development` |\n| `DB_HOST` | PostgreSQL host | `localhost` |\n| `DB_PORT` | PostgreSQL port | `5432` |\n| `DB_NAME` | Database name | `db_name` |\n| `DB_USER` | Database user | `user` |\n| `DB_PASSWORD` | Database password | `password` |\n\n## 🧪 Example Requests\n\n### Create a Feature Flag\n\n```bash\ncurl -X POST http://localhost:3001/api/flags \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"key\": \"new-checkout-flow\",\n    \"name\": \"New Checkout Flow\",\n    \"description\": \"Enable the new checkout experience\",\n    \"enabled\": false\n  }'\n```\n\n### Assign Flag to User\n\n```bash\ncurl -X POST http://localhost:3001/api/users/user123/flags/1 \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"enabled\": true\n  }'\n```\n\n### Track Event\n\n```bash\ncurl -X POST http://localhost:3001/api/metrics/events \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"flag_id\": 1,\n    \"user_id\": \"user123\",\n    \"event_type\": \"viewed\",\n    \"metadata\": {\"page\": \"checkout\"}\n  }'\n```\n\n## 🐛 Error Handling\n\nThe API uses consistent error responses:\n\n```json\n{\n  \"error\": \"Error message\"\n}\n```\n\nError status codes:\n- `400`: Bad Request (validation errors)\n- `404`: Not Found\n- `409`: Conflict (duplicate resources)\n- `500`: Internal Server Error\n\n## 📝 License\n\nISC\n\n## 🤝 Contributing\n\n1. Follow the existing code structure\n2. Keep routes thin - all logic in services\n3. Add Zod schemas for validation\n4. Update Swagger documentation\n5. Test your changes\n6. Push your codes\n\n## 📞 Support\n\nFor issues and questions, please refer to the main project documentation.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu-leslie%2Fskitt_be","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fu-leslie%2Fskitt_be","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu-leslie%2Fskitt_be/lists"}