# Kattalyx Backend Backend API for the Kattalyx platform built with Node.js, Express, TypeScript, and MongoDB. ## 🚀 Quick Start ### Prerequisites - **Node.js** (v18 or higher) - **MongoDB** (local installation or MongoDB Atlas account) - **npm** or **yarn** ### Installation 1. **Clone the repository** (if you haven't already) ```bash cd kat-backend ``` 2. **Install dependencies** ```bash npm install ``` 3. **Set up environment variables** ```bash cp .env.example .env ``` Then edit `.env` with your actual values. See [ENV_SETUP.md](./ENV_SETUP.md) for detailed instructions. 4. **Run the development server** ```bash npm run dev ``` 5. **Build for production** ```bash npm run build npm start ``` ## 📁 Project Structure ``` kat-backend/ ├── src/ │ ├── config/ # Configuration files (database, cloudinary, etc.) │ ├── controllers/ # Route controllers │ ├── middleware/ # Custom middleware (auth, logging, error handling) │ ├── models/ # Mongoose models │ ├── routes/ # API routes │ ├── services/ # Business logic and services │ ├── index.ts # Application setup │ └── server.ts # Server entry point ├── dist/ # Compiled JavaScript (generated) ├── .env.example # Environment variables template ├── ENV_SETUP.md # Detailed environment setup guide ├── ARCHITECTURE.md # Architecture documentation ├── LOGGING_GUIDE.md # Logging guidelines ├── SWAGGER_GUIDE.md # API documentation guide ├── package.json └── tsconfig.json ``` ## 🔧 Available Scripts | Command | Description | |---------|-------------| | `npm run dev` | Start development server with hot reload | | `npm run build` | Compile TypeScript to JavaScript | | `npm start` | Run production server (requires build first) | ## 🌐 API Documentation Once the server is running, access the Swagger API documentation at: ``` http://localhost:3000/api-docs ``` For more details on API documentation, see [SWAGGER_GUIDE.md](./SWAGGER_GUIDE.md). ## ⚙️ Environment Variables This project requires several environment variables to be configured. See [ENV_SETUP.md](./ENV_SETUP.md) for a complete guide. **Quick reference:** - `NODE_ENV` - Environment (development/production) - `PORT` - Server port (default: 3000) - `MONGO_URI` - MongoDB connection string - `JWT_SECRET` - Secret for JWT tokens - `CLOUDINARY_CLOUD_NAME` - Cloudinary cloud name - `CLOUDINARY_API_KEY` - Cloudinary API key - `CLOUDINARY_API_SECRET` - Cloudinary API secret ## 🏗️ Architecture This project follows a modular architecture with clear separation of concerns: - **Routes** → **Controllers** → **Services** → **Models** - Middleware for authentication, logging, and error handling - Centralized error handling - Structured logging with Morgan For more details, see [ARCHITECTURE.md](./ARCHITECTURE.md). ## 📝 Logging The application uses Morgan for HTTP request logging with different configurations for development and production environments. See [LOGGING_GUIDE.md](./LOGGING_GUIDE.md) for more information. ## 🔐 Authentication The API uses JWT (JSON Web Tokens) for authentication: 1. Users authenticate via `/api/auth/login` or `/api/auth/register` 2. A JWT token is returned 3. Include the token in the `Authorization` header: `Bearer ` 4. Protected routes verify the token using the auth middleware ## 🗄️ Database This project uses MongoDB with Mongoose ODM: - **Local Development**: MongoDB running on `localhost:27017` - **Production**: MongoDB Atlas (recommended) Database connection is configured in `src/config/database.ts`. ## ☁️ File Uploads File uploads are handled using: - **Multer** - Multipart form data parsing - **Cloudinary** - Cloud storage for images and files Configuration is in `src/config/cloudinary.config.ts`. ## 🛠️ Development ### Code Style - TypeScript for type safety - ES Modules (`"type": "module"` in package.json) - Async/await for asynchronous operations - Centralized error handling ### Adding New Features 1. **Create a model** in `src/models/` 2. **Create a controller** in `src/controllers/` 3. **Create routes** in `src/routes/` 4. **Add Swagger documentation** (see SWAGGER_GUIDE.md) 5. **Register routes** in `src/index.ts` ## 🚢 Deployment ### Vercel / Railway / Render 1. Connect your repository 2. Set environment variables in the platform dashboard 3. Set build command: `npm run build` 4. Set start command: `npm start` ### Heroku ```bash heroku create your-app-name heroku config:set NODE_ENV=production heroku config:set MONGO_URI=your-mongo-uri # ... set other env vars git push heroku main ``` ## 🐛 Troubleshooting ### Common Issues **MongoDB Connection Failed** - Ensure MongoDB is running locally, or - Check your MongoDB Atlas connection string - Verify IP whitelist in MongoDB Atlas **Port Already in Use** - Change the `PORT` in your `.env` file - Or stop the process using the port **JWT Errors** - Ensure `JWT_SECRET` is set in `.env` - Check token format: `Bearer ` **Cloudinary Upload Fails** - Verify all Cloudinary credentials are set - Check Cloudinary dashboard for quota limits ## 📚 Additional Documentation - [ENV_SETUP.md](./ENV_SETUP.md) - Environment setup guide - [ARCHITECTURE.md](./ARCHITECTURE.md) - Architecture overview - [LOGGING_GUIDE.md](./LOGGING_GUIDE.md) - Logging guidelines - [SWAGGER_GUIDE.md](./SWAGGER_GUIDE.md) - API documentation guide ## 🤝 Contributing 1. Create a feature branch 2. Make your changes 3. Test thoroughly 4. Submit a pull request ## 📄 License [Add your license here] ## 👥 Team Kattalyx Development Team --- **Need help?** Check the documentation files or contact the development team. # Kattalyx-labs-backend # Kattalyx-labs-backend