Skip to content

README.md

Latest commit

 

History

History
159 lines (124 loc) · 4.48 KB

README.md

File metadata and controls

159 lines (124 loc) · 4.48 KB

Plotter API

A scalable REST API built with Fastify, TypeScript, MongoDB, and clean architecture for React Native applications with Google authentication.

🚀 Features

  • Google Authentication - Secure authentication using Google ID tokens
  • Group Management - Role-based group system (owner, admin, participant)
  • Real-time Notifications - WebSocket support for live updates
  • Auto-generated Documentation - OpenAPI/Swagger documentation from Zod schemas
  • Clean Architecture - Domain-driven design with clear separation of concerns
  • Type Safety - Full TypeScript coverage with Zod validation
  • Scalable - MongoDB with Redis caching and horizontal scaling support

🛠️ Tech Stack

  • Framework: Fastify with TypeScript
  • Database: MongoDB with Mongoose ODM
  • Caching: Redis
  • Authentication: JWT with Clerk
  • Validation: Zod schemas
  • Documentation: OpenAPI/Swagger
  • Real-time: WebSockets
  • External Services: SendGrid (email), Twilio (SMS), Google Cloud Storage

📋 Prerequisites

  • Node.js 18+
  • MongoDB
  • Redis
  • Google Cloud Console project (for OAuth)

🚀 Quick Start

  1. Clone and install dependencies

    git clone <repository-url>
cd plotter-api
npm install

  2. Set up environment variables

    cp env.example .env
# Edit .env with your configuration

  3. Required Environment Variables

    JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
MONGODB_URI=mongodb://localhost:27017/plotter-api
REDIS_URL=redis://localhost:6379

  4. Start development server

    npm run dev

  5. View API documentation Open http://localhost:3000/documentation

📖 API Endpoints

Authentication

  • POST /auth/google - Authenticate with Google ID token
  • GET /auth/me - Get current user information

Groups

  • GET /groups - List user's groups
  • POST /groups - Create a new group
  • GET /groups/:id - Get group details
  • PUT /groups/:id - Update group (admin+)
  • DELETE /groups/:id - Delete group (owner only)
  • GET /groups/:id/members - List group members
  • POST /groups/:id/members - Add member (admin+)
  • PUT /groups/:id/members/:userId - Update member role (admin+)
  • DELETE /groups/:id/members/:userId - Remove member (admin+)

Users

  • GET /users/me - Get current user profile
  • PUT /users/me - Update current user profile

Files

  • POST /files/upload - Upload file to Google Cloud Storage
  • GET /files/:id - Get file information

WebSocket

  • GET /ws - WebSocket connection for real-time updates

🏗️ Architecture

src/
├── app.ts                    # Main Fastify app setup
├── server.ts                 # Server entry point
├── plugins/                  # Auto-loaded plugins
│   ├── auth.ts              # Authentication & authorization
│   ├── cors.ts              # CORS configuration
│   ├── database.ts          # MongoDB & Redis connections
│   ├── swagger.ts           # OpenAPI documentation
│   └── websocket.ts         # WebSocket setup
├── routes/                   # Auto-loaded routes
│   ├── auth/                # Authentication endpoints
│   ├── groups/              # Group management
│   ├── users/               # User management
│   └── files/               # File operations
├── domain/                   # Domain entities
├── application/              # Business logic
├── infrastructure/           # External services
├── presentation/             # Schemas & controllers
└── config/                   # Configuration
  1. Subsequent Requests:
    • Include JWT in Authorization header: Bearer <token>
    • Backend validates JWT and extracts user/group/role info

🔧 Development

# Development with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test

# Lint code
npm run lint

🚀 Deployment

The API is designed to be deployed on Railway or similar platforms:

  1. Connect your repository to Railway
  2. Set environment variables
  3. Deploy automatically

📊 Monitoring

  • Health check: GET /health
  • Logs: Structured logging with Pino
  • Error tracking: Built-in error handling

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request