# API Specification & Microservices Contract
## Personal & Agency Portfolio Platform: Er. Sujeet Pandit & TechoMaster

---

## 1. API Architecture & Design Principles

The API follows modern **RESTful conventions** with standardized JSON envelopes, strict HTTP status codes, CORS validation, edge-rate limiting, and OpenAPI 3.0 compliance.

- **Base URL (Production)**: `https://api.techomaster.in/v1` or `/api/v1` (Serverless Edge)
- **Data Format**: `application/json; charset=utf-8`
- **Rate Limiting**: 5 requests per minute for public write endpoints (`/contact`, `/quote-request`), 100 requests per minute for read endpoints.

---

## 2. Endpoint Index

| Method | Endpoint | Description | Auth | Rate Limit |
|---|---|---|---|---|
| `POST` | `/api/v1/contact` | Submit general contact message | Public | 5 req / min / IP |
| `POST` | `/api/v1/quote-request` | Submit customized project scope estimate | Public | 5 req / min / IP |
| `GET` | `/api/v1/projects` | Query portfolio projects with filters | Public | 100 req / min |
| `GET` | `/api/v1/projects/:slug` | Retrieve full project case study | Public | 100 req / min |
| `GET` | `/api/v1/testimonials` | Retrieve verified client testimonials | Public | 100 req / min |
| `POST` | `/api/v1/analytics/event` | Ingest anonymized visitor telemetry | Public | 60 req / min |
| `GET` | `/api/v1/health` | Service health & latency check | Public | Unlimited |

---

## 3. Detailed Endpoint Contracts

### 3.1 `POST /api/v1/contact`

Submits a new inquiry from the portfolio contact form. Automatically triggers email alerts and Telegram/Slack notifications to Sujeet Pandit.

#### Request Headers
```http
Content-Type: application/json
Accept: application/json
```

#### Request Payload
```json
{
  "name": "David Mitchell",
  "email": "david.mitchell@innovatetech.io",
  "phone": "+1 415 890 1234",
  "subject": "Enterprise AI Analytics Integration",
  "serviceType": "AI & Machine Learning",
  "message": "We are looking for a senior AI engineering team to architect our real-time predictive analytics dashboard."
}
```

#### Success Response (`201 Created`)
```json
{
  "success": true,
  "message": "Thank you, David. Your inquiry has been received. Er. Sujeet Pandit will respond within 24 hours.",
  "data": {
    "inquiryId": "inq_78f1a8b4-92c1-4567-b89a-0e12d3456789",
    "receivedAt": "2026-08-16T09:50:00.000Z",
    "status": "QUEUED_FOR_DISPATCH"
  }
}
```

#### Error Response (`422 Unprocessable Entity`)
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The submission contained invalid fields.",
    "details": [
      {
        "field": "email",
        "issue": "Must be a valid email address format."
      }
    ]
  }
}
```

---

### 3.2 `POST /api/v1/quote-request`

Submits a calculated quote request generated from the interactive Project Scope & Cost Estimator.

#### Request Payload
```json
{
  "clientName": "Elena Rostova",
  "clientEmail": "elena@cloudscale.ai",
  "clientPhone": "+91 98765 43210",
  "projectType": "AI & Machine Learning",
  "deliveryTimeline": "Standard (4 - 8 Weeks)",
  "selectedAddons": [
    "DevOps & CI/CD Pipeline",
    "Enterprise UI/UX Design System",
    "24/7 Production SLA & Support"
  ],
  "estimatedBudget": {
    "min": 4500,
    "max": 8500,
    "currency": "USD"
  },
  "projectNotes": "Looking to deploy a multi-tenant LLM wrapper with RAG pipeline on AWS."
}
```

#### Success Response (`201 Created`)
```json
{
  "success": true,
  "message": "Your project scope estimate has been registered. An official scope document will be shared shortly.",
  "data": {
    "estimateReference": "EST-2026-9812",
    "generatedAt": "2026-08-16T09:52:10.000Z",
    "currency": "USD",
    "bracket": "$4,500 - $8,500"
  }
}
```

---

### 3.3 `GET /api/v1/projects`

Retrieves a list of showcased case studies with optional category filtering.

#### Query Parameters
- `category` (optional, string): `AI_ML`, `WEB_DEV`, `MOBILE_APP`, `CLOUD_DEVOPS`, `ENTERPRISE`
- `featured` (optional, boolean): `true` / `false`
- `limit` (optional, integer): Default `12`

#### Success Response (`200 OK`)
```json
{
  "success": true,
  "data": [
    {
      "id": "proj_01",
      "slug": "ai-predictive-analytics-platform",
      "title": "AI-Powered Analytics Platform",
      "category": "AI_ML",
      "description": "Enterprise-grade real-time predictive analytics and anomaly detection engine processing over 10M events daily.",
      "client": "Global Enterprise Systems",
      "techStack": ["Python", "FastAPI", "TensorFlow", "React", "Docker", "AWS"],
      "metrics": [
        { "label": "Efficiency Boost", "value": "+42%" },
        { "label": "Throughput", "value": "10M Events/Day" },
        { "label": "Uptime", "value": "99.99%" }
      ],
      "liveUrl": "https://techomaster.in/portfolio",
      "githubUrl": "https://github.com/sujeet3"
    },
    {
      "id": "proj_02",
      "slug": "omagro-enterprise-commerce",
      "title": "Agritech & Industrial Commerce Suite",
      "category": "ENTERPRISE",
      "description": "High-concurrency e-commerce and supply chain distribution system for global agricultural exporters.",
      "client": "Argade Group / Om Agro India",
      "techStack": ["Node.js", "Express", "PostgreSQL", "React", "TailwindCSS", "Redis"],
      "metrics": [
        { "label": "Orders Processed", "value": "50K+" },
        { "label": "Page Speed", "value": "98/100" }
      ],
      "liveUrl": "https://omagroindia.com",
      "githubUrl": "https://github.com/sujeet21git"
    }
  ]
}
```

---

## 4. Webhook Notification Flow (Telegram / Discord / Email)

```mermaid
sequenceDiagram
    autonumber
    actor Client as Visitor / Client
    participant API as Portfolio Serverless API
    participant Mail as Resend / SendGrid SMTP
    participant Bot as Telegram Bot Alert
    participant Admin as Er. Sujeet Pandit

    Client->>API: Submits Inquiry / Scope Quote
    API->>API: Validate & Sanitize Input
    par Email Dispatch
        API->>Mail: Send Auto-Reply to Client
        API->>Mail: Send Lead Alert to info@techomaster.com
    and Telegram Push Notification
        API->>Bot: Post Message to Admin Telegram Channel
        Bot-->>Admin: Instant Mobile Push Notification
    end
    API-->>Client: 201 Created JSON Confirmation
```