turash/bugulma/frontend/BACKEND_ENDPOINTS_NEEDED.md

# Backend Endpoints Needed

This document lists all backend endpoints that need to be implemented to complete the frontend-to-backend migration.

## AI/LLM Endpoints

Already documented in `BACKEND_AI_ENDPOINTS.md`:

- ✅ `POST /api/ai/extract/text`
- ✅ `POST /api/ai/extract/file`
- ✅ `POST /api/ai/analyze/symbiosis`
- ✅ `POST /api/ai/web-intelligence`
- ✅ `POST /api/ai/search-suggestions`
- ✅ `POST /api/ai/generate/description`
- ✅ `POST /api/ai/generate/historical-context`
- ✅ `POST /api/ai/chat`

**Additional needed:**

- `POST /api/ai/chat/stream` - Streaming chat (SSE or WebSocket)

---

## Proposal Endpoints

### List Proposals

**GET** `/api/proposals`

**Query Parameters:**

- `organization_id` (optional) - Filter by organization
- `status` (optional) - Filter by status (pending, accepted, rejected)
- `type` (optional) - Filter by type (incoming, outgoing)

**Response:**

```json
{
  "proposals": [
    {
      "id": "prop-1",
      "from_org_id": "org-1",
      "to_org_id": "org-2",
      "resource_id": "resource-1",
      "resource_type": "input",
      "resource_name": "Waste Heat",
      "message": "Proposal message...",
      "status": "pending",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 1
}
```

### Get Proposal

**GET** `/api/proposals/:id`

**Response:**

```json
{
  "id": "prop-1",
  "from_org_id": "org-1",
  "to_org_id": "org-2",
  "resource_id": "resource-1",
  "resource_type": "input",
  "resource_name": "Waste Heat",
  "message": "Proposal message...",
  "status": "pending",
  "created_at": "2024-01-01T00:00:00Z"
}
```

### Create Proposal

**POST** `/api/proposals`

**Request:**

```json
{
  "from_org_id": "org-1",
  "to_org_id": "org-2",
  "resource_id": "resource-1",
  "resource_type": "input",
  "resource_name": "Waste Heat",
  "message": "Proposal message..."
}
```

**Response:**

```json
{
  "id": "prop-1",
  "status": "pending",
  "created_at": "2024-01-01T00:00:00Z",
  ...
}
```

### Update Proposal Status

**PUT** `/api/proposals/:id/status`

**Request:**

```json
{
  "status": "accepted" // or "rejected", "pending"
}
```

**Response:**

```json
{
  "id": "prop-1",
  "status": "accepted",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

### Get Proposals for Organization

**GET** `/api/proposals/organization/:orgId`

**Query Parameters:**

- `type` (optional) - "incoming" or "outgoing"

**Response:**

```json
{
  "incoming": [...],
  "outgoing": [...]
}
```

---

## Matching Endpoints

### Direct Symbiosis Matches

**GET** `/api/matching/organization/:orgId/direct`

**Response:**

```json
{
  "providers": [
    {
      "partner_id": "org-2",
      "partner_name": "Partner Corp",
      "resource": "Waste Heat",
      "resource_flow_id": "flow-1"
    }
  ],
  "consumers": [
    {
      "partner_id": "org-3",
      "partner_name": "Consumer Corp",
      "resource": "Steam",
      "resource_flow_id": "flow-2"
    }
  ]
}
```

**Note:** This should use ResourceFlows from the backend, not the old needs/offers model.

---

## Analytics Endpoints

### Connection Statistics

**GET** `/api/analytics/connections`

**Response:**

```json
{
  "total_connections": 42,
  "active_connections": 15,
  "potential_connections": 27
}
```

### Supply and Demand Analysis

**GET** `/api/analytics/supply-demand`

**Response:**

```json
{
  "top_needs": [
    { "item": "Waste Heat", "count": 12 },
    { "item": "Steam", "count": 8 }
  ],
  "top_offers": [
    { "item": "Cooling Water", "count": 15 },
    { "item": "CO2", "count": 10 }
  ]
}
```

### Dashboard Statistics

**GET** `/api/analytics/dashboard`

**Response:**

```json
{
  "total_organizations": 50,
  "total_sites": 75,
  "total_resource_flows": 200,
  "total_matches": 150,
  "active_proposals": 25,
  "recent_activity": [...]
}
```

---

## Organization Endpoints

### Search Organizations

**GET** `/api/organizations/search`

**Query Parameters:**

- `q` (optional) - Search query
- `sectors` (optional) - Comma-separated sector IDs
- `sort` (optional) - Sort option (name_asc, name_desc, sector_asc, etc.)
- `limit` (optional) - Result limit
- `offset` (optional) - Pagination offset

**Response:**

```json
{
  "organizations": [...],
  "count": 10,
  "total": 50
}
```

### Similar Organizations

**GET** `/api/organizations/:id/similar`

**Query Parameters:**

- `limit` (optional, default: 5) - Number of results

**Response:**

```json
{
  "organizations": [
    {
      "id": "org-2",
      "name": "Similar Corp",
      "sector": "manufacturing",
      "similarity_score": 0.85
    }
  ]
}
```

---

## Implementation Priority

### Phase 1 - Critical (Security & Data)

1. ✅ Chat endpoints (security)
2. ✅ Proposal endpoints (data persistence)
3. ✅ Direct symbiosis matching (business logic)

### Phase 2 - Important (Performance)

4. Analytics endpoints
5. Organization search endpoint
6. Similar organizations endpoint

### Phase 3 - Optimization

7. Caching strategies
8. Rate limiting
9. WebSocket/SSE for real-time updates

---

## Notes

- All endpoints require authentication (Bearer token) except where noted
- Use consistent error response format: `{ "error": "message", "code": "ERROR_CODE" }`
- Consider pagination for list endpoints
- Add rate limiting for AI endpoints
- Consider caching for analytics endpoints