PingClients API

A SaaS platform for automated reminders that helps companies notify their clients about recurring services (e.g., AC maintenance every 6 months).

Features

• Company Management: Registration, authentication, and profile management
• Client Management: CRUD operations for managing service clients
• Automated Reminders: Scheduled notifications based on service intervals
• Multi-channel Notifications: Email and SMS notifications
• Analytics Dashboard: Track delivery, open rates, and bookings
• Admin Panel: Platform-wide management and monitoring

Tech Stack

• Backend: Go with Gin framework
• Database: PostgreSQL with GORM
• Authentication: JWT tokens
• Notifications: SendGrid (Email) + Twilio (SMS)
• Architecture: REST API

Quick Start

Prerequisites

• Go 1.21+
• PostgreSQL
• SendGrid API key (for email)
• Twilio account (for SMS)

Installation

1. Clone the repository:

git clone <repository-url>
cd pingclients-api

2. Install dependencies:

go mod tidy

3. Set up environment variables:

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

4. Run database migrations:

go run main.go

5. Start the server:

go run main.go

The API will be available at http://localhost:8080

API Endpoints

Authentication

• POST /api/v1/auth/register - Company registration
• POST /api/v1/auth/login - Login

Company Management

• GET /api/v1/company/profile - Get company profile
• PUT /api/v1/company/profile - Update company profile
• GET /api/v1/company/dashboard - Get dashboard data
• GET /api/v1/company/analytics - Get analytics

Client Management

• GET /api/v1/clients - List clients (with pagination & search)
• POST /api/v1/clients - Create new client
• GET /api/v1/clients/:id - Get client details
• PUT /api/v1/clients/:id - Update client
• DELETE /api/v1/clients/:id - Delete client

Reminder Management

• GET /api/v1/reminders - List reminders
• POST /api/v1/reminders - Create reminder
• GET /api/v1/reminders/:id - Get reminder details
• PUT /api/v1/reminders/:id - Update reminder
• DELETE /api/v1/reminders/:id - Delete reminder

Template Management

• GET /api/v1/templates - List notification templates
• POST /api/v1/templates - Create template
• GET /api/v1/templates/:id - Get template
• PUT /api/v1/templates/:id - Update template
• DELETE /api/v1/templates/:id - Delete template

Admin (Admin only)

• GET /api/v1/admin/companies - List all companies
• GET /api/v1/admin/companies/:id - Get company details
• PUT /api/v1/admin/companies/:id/status - Update company status
• GET /api/v1/admin/stats - Platform statistics

Webhooks (Tracking)

• POST /api/v1/webhooks/email/opened/:reminder_id - Track email open
• POST /api/v1/webhooks/email/clicked/:reminder_id - Track link click
• POST /api/v1/webhooks/service/booked/:reminder_id - Track service booking

Database Schema

The application uses the following main entities:

• Users: Authentication and basic user info
• Companies: B2B customers using the platform
• Clients: End customers of the companies
• Reminders: Scheduled notifications
• NotificationTemplates: Customizable email/SMS templates
• Analytics: Tracking data for notifications

Configuration

Key environment variables:

• DATABASE_URL: PostgreSQL connection string
• JWT_SECRET: Secret key for JWT tokens
• SENDGRID_API_KEY: SendGrid API key for emails
• TWILIO_SID & TWILIO_TOKEN: Twilio credentials for SMS
• PORT: Server port (default: 8080)

Reminder Scheduling

The application includes an automated scheduler that:

1. Runs every hour to check for due reminders
2. Processes pending reminders based on scheduled_date
3. Sends notifications via configured channels (email/SMS)
4. Updates reminder status and analytics
5. Automatically schedules next reminder after service booking

Security Features

• JWT-based authentication
• Password hashing with bcrypt
• Role-based access control (admin, company)
• Input validation and sanitization
• Soft deletes for data preservation

Development

Project Structure

pingclients-api/
├── main.go                    # Application entry point
├── internal/
│   ├── api/                   # HTTP handlers and routes
│   │   ├── handlers/          # Request handlers
│   │   └── routes.go          # Route definitions
│   ├── auth/                  # Authentication logic
│   ├── config/                # Configuration management
│   ├── database/              # Database connection and migrations
│   ├── models/                # Database models
│   ├── notifications/         # Email/SMS services
│   └── scheduler/             # Reminder scheduling
└── docs/                      # Documentation

Adding New Features

1. Update models in internal/models/
2. Create handlers in internal/api/handlers/
3. Add routes in internal/api/routes.go
4. Update database migrations if needed

License

[Add your license here]