# Technical Requirements Document for PhoneMate

## 1. Overview

This document defines the technical architecture and microservices-based design for PhoneMate's backend API. The solution will be developed with FastAPI and all endpoint communications will require Bearer token authentication for secure API access.

## 2. Architecture Overview

- **Microservices Architecture:**
  - Each core function (authentication, telephony, scheduling, payment, reporting, etc.) is developed as an independent service.
  - Services communicate over RESTful APIs or lightweight messaging protocols when necessary.
- **Backend Platform:**
  - Implemented using FastAPI due to its performance and modern Python standards.
  - Endpoints are stateless and secured by requiring Bearer tokens for every API call.
- **Database:**
  - MongoDB is used to persist user profiles, scheduling details, transaction histories, and interaction logs.
- **Deployment Environment:**
  - Ubuntu-based servers using traditional deployment methods initially.
  - Containerization with Docker may be pursued later for enhanced portability and scalability.

## 3. Microservices Description

### 3.1. Authentication & User Management Service

- **Features:**
  - Secure user registration and login.
  - Implementation of Bearer token authentication using OAuth2/JWT (leveraging FastAPI's security dependencies).
- **Endpoints:**
  - `/api/auth/signup`, `/api/auth/signin`, `/api/auth/logout`
- **Token Security:**
  - Every API call must present a valid Bearer token for access.

### 3.2. Telephony & AI Bot Integration Service

- **Features:**
  - Integration with Twilio for phone provisioning and call routing.
  - Integration with Retellai for managing pre-defined AI bot personalities.
- **Endpoints:**
  - `/api/telephony/phone-setup`, `/api/telephony/forward-calls`, `/api/telephony/bot-setup`
- **Security:**
  - Endpoints are secured via the Bearer token mechanism.

### 3.3. Scheduling & Availability Service

- **Features:**
  - Manage business availability scheduling for the UK timezone.
  - Provide API endpoints for booking management, including creating, updating, or canceling bookings.
- **Endpoints:**
  - `/api/schedule/availability`, `/api/schedule/bookings`, `/api/schedule/calendar-view`
- **Security:**
  - Require Bearer token authentication for all scheduling actions.

### 3.4. Service Management API

- **Features:**
  - CRUD endpoints to manage a fixed list of service categories.
- **Endpoints:**
  - `/api/services/list`, `/api/services/update`
- **Security:**
  - Protected using Bearer token authentication.

### 3.5. Payment Processing Service

- **Features:**
  - Integration with Stripe (or Lemonsquishy) for pay-as-you-go transactions.
  - Webhook endpoints to handle payment events and transaction confirmations.
- **Endpoints:**
  - `/api/payment/initiate`, `/api/payment/webhook`, `/api/payment/history`
- **Security:**
  - All payment endpoints require valid Bearer tokens and must operate over HTTPS.

### 3.6. Reporting & Dashboard Service

- **Features:**
  - Aggregate and expose data from all services (call volumes, bookings, financial transactions) via reporting endpoints.
- **Endpoints:**
  - `/api/reporting/dashboard`, `/api/reporting/call-logs`, `/api/reporting/transaction-stats`
- **Security:**
  - Secured via Bearer token to ensure only authenticated users can retrieve sensitive data.

## 4. Non-Functional Requirements

- **Performance:**
  - Maintain sub-1000ms latency for API responses.
- **Security:**
  - Use FastAPI’s OAuth2/JWT for Bearer token authentication.
  - Ensure HTTPS is enforced on all endpoints and secure data transmission.
- **Scalability:**
  - Design services to support plug-and-play integration with additional modules and third-party APIs.
- **Compliance:**
  - Follow GDPR standards and UK data protection regulations.

## 5. Deployment & Monitoring

- **Deployment Approach:**
  - Initially deploy on Ubuntu-based servers using a traditional deployment model.
  - Consider containerization (Docker) for future enhancements.
- **Monitoring:**
  - Implement logging, performance monitoring, and alerts (using tools like Prometheus and Grafana).
- **Service Discovery:**
  - Implement an API gateway and/or service registry if necessary to manage microservices endpoints.
