File size: 20,781 Bytes
205f25f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
# BeFree API Reference

This document provides a complete inventory of the REST API endpoints exposed by the BeFree backend server, including authentication requirements, request payloads, and response structures.

---

## Global Authentication Rules
- **Bearer Tokens**: Endpoints requiring authentication look for a JWT token in the `Authorization: Bearer <token>` header.
- **Roles**:
  - `tester` (default): View dashboards, upload and review statements.
  - `manager`: Access dashboard metrics, review history, and trigger exports.
  - `admin`: Full access, including rule manipulation, audit logs, categories, database resets, and administrative commands.

---

## 1. Authentication Endpoints

### `POST /api/v1/auth/login`
- **Auth Required**: No
- **Request Body**: Form parameters (`username`, `password`)
- **Response Schema**: `TokenResponse` (`access_token`, `token_type`, `role`, `username`)
- **Description**: Verifies credentials and returns a signed JWT access token.

### `POST /api/v1/auth/logout`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: None (retrieves token from authorization header)
- **Response Schema**: `{"status": "success", "message": "Logged out"}`
- **Description**: Revokes the active session token in the database.

### `GET /api/v1/auth/me`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `UserProfile` (`id`, `username`, `email`, `fullName`, `role`)
- **Description**: Returns the profile details of the currently authenticated user.

### `POST /api/v1/auth/seed-users`
- **Auth Required**: Yes (requires `X-Seed-Secret` header matching `SEED_SECRET` env var)
- **Response Schema**: `{"status": "success", "seeded_count": int}`
- **Description**: Seeds initial system users (`admin`, `manager`, `tester`) into the PostgreSQL database.

---

## 2. Dashboard Endpoints

### `GET /api/v1/dashboard/metrics`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `DashboardMetrics` (`totalStatements`, `processedSuccessfully`, `failedStatements`, `averageAccuracy`, `totalFlaggedTransactions`)
- **Description**: Aggregates high-level processing statistics for the main dashboard display.

### `GET /api/v1/dashboard/recent-activity`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `List[ActivityItem]` (`id`, `timestamp`, `username`, `action`, `description`)
- **Description**: Lists recent database audit log activities.

### `GET /api/v1/dashboard/recent-statements`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `List[StatementSummary]` (`id`, `fileName`, `status`, `uploadedAt`, `accuracy`)
- **Description**: Lists recently processed statement metadata.

---

## 3. Statement Processing Endpoints

### `POST /api/v1/statements/upload`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: Multipart form data with key `files` (array of PDF files)
- **Response Schema**: `UploadInitResponse` (`statementId`, `fileName`, `status`, `ocrFallbackTriggered`)
- **Description**: Ingests PDF files, initializes the transaction database, and caches the raw PDFs on disk.

### `POST /api/v1/statements/{statement_id}/detect-layout`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `HeaderDetectionResultModel`
- **Description**: Analyzes pages in the statement to automatically detect header coordinates and column mappings.

### `GET /api/v1/statements/{statement_id}/layout`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `HeaderDetectionResultModel`
- **Description**: Retrieves the cached or detected column layout map.

### `GET /api/v1/statements/{statement_id}/page-image/{page_num}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: PNG binary stream
- **Description**: Generates and serves a rasterized PNG image of a statement page (used for visual verification in the coordinate inspector).

### `POST /api/v1/statements/{statement_id}/verify-layout`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `HeaderDetectionResultModel`
- **Response Schema**: `{"success": true}`
- **Description**: Saves layout coordinates adjusted manually by the user in the UI coordinate builder.

### `PATCH /api/v1/statements/{statement_id}/layout/column/{col_name}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: JSON mapping for x-coordinates (`x_min`, `x_max`)
- **Response Schema**: `{"success": true}`
- **Description**: Modifies coordinate ranges for a single column.

### `POST /api/v1/statements/{statement_id}/process`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true, "message": "Extraction started"}`
- **Description**: Initiates transaction cell extraction and audits in a background thread.

### `POST /api/v1/statements/{statement_id}/finalise`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true}`
- **Description**: Finalizes the statement review and generates the default spreadsheet.

### `GET /api/v1/statements/{statement_id}/processing`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `ProcessingState`
- **Description**: Polls the background thread extraction progress, stages completed, and remaining duration.

### `POST /api/v1/statements/{statement_id}/processing/cancel`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `None`
- **Description**: Cancels background processing for a statement and sets its status to `cancelled`.

### `POST /api/v1/statements/{statement_id}/save-progress`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"status": "success", "message": "Progress saved"}`
- **Description**: Forces writing the active transaction and correction log states to the excel cached workbook.

### `GET /api/v1/statements/{statement_id}/pdf`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: PDF binary stream
- **Description**: Downloads the raw uploaded PDF file.

---

## 4. Transaction Endpoints

### `GET /api/v1/statements/{statement_id}/transactions`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `page` (int), `pageSize` (int), `search` (str), `status` (str), `pageNum` (int), `confidence` (str: `high`|`low`)
- **Response Schema**: `TransactionsPage` (`items`: `List[TransactionRowModel]`, `total`: int, `page`: int, `pageSize`: int)
- **Description**: Retrieves a paginated list of transactions, supporting search queries, status filters, page limits, and date windowing configurations.

### `POST /api/v1/statements/{statement_id}/transactions`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `TransactionCreatePayload` (`pageNumber`, `date`, `description`, `debit`, `credit`, `balance`)
- **Response Schema**: `TransactionRowModel`
- **Description**: Inserts a manual transaction row, triggers a statement re-audit, and persists the cache.

### `GET /api/v1/statements/{statement_id}/transactions/{tx_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `TransactionRowModel`
- **Description**: Returns a single transaction details.

### `PATCH /api/v1/statements/{statement_id}/transactions/{tx_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `TransactionUpdatePayload` (`date`, `description`, `debit`, `credit`, `balance`, `category`)
- **Response Schema**: `TransactionRowModel`
- **Description**: Updates field values, clears historical audit warnings, and recalculates running balances.

### `DELETE /api/v1/statements/{statement_id}/transactions/{tx_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `None`
- **Description**: Deletes a transaction row and updates subsequent running balances.

---

## 5. Review & HITL Endpoints

### `GET /api/v1/statements/{statement_id}/review-session`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `ReviewSession` (`statementId`, `fileName`, `bankName`, `pdfUrl`, `uploadedAt`, `uploadedBy`)
- **Description**: Prepares review parameters, returning document URLs and upload history.

### `GET /api/v1/statements/{statement_id}/review/metrics`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `ReviewMetrics` (`totalTransactions`, `needsAttention`, `lowConfidence`, `balanceIssues`, `gapsDetected`, `overallAccuracy`)
- **Description**: Aggregates discrepancy indicators and arithmetic error metrics for the review interface.

### `POST /api/v1/statements/{statement_id}/auto-swap-all`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": True, "swappedCount": int}`
- **Description**: Triggers a mathematical audit pass that automatically swaps debit and credit fields on matching rows to correct ledger balance progression.

### `POST /api/v1/statements/{statement_id}/transactions/{tx_id}/swap-debit-credit`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `TransactionRowModel`
- **Description**: Forcefully swaps the debit and credit columns of a single transaction and updates balances.

### `POST /api/v1/statements/{statement_id}/pages/{page_num}/review`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true, "updatedCount": int}`
- **Description**: Bulk marks all transactions on a page as manually verified, clearing audit warnings.

### `POST /api/v1/statements/{statement_id}/re-audit`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `ReAuditPayload` (`pageNum`)
- **Response Schema**: `{"success": true, "auditResult": {"pageNum": int, "checked": int, "issues": int}}`
- **Description**: Triggers a full-statement auto-swap audit and reports remaining issues for the specified page.

### `GET /api/v1/statements/{statement_id}/flagged`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `severity` (str), `bank` (str), `search` (str)
- **Response Schema**: `List[FlaggedTransaction]` (`id`, `severity`, `issueType`, `pageNum`, `confidence`, `amount`, `description`, `statementId`)
- **Description**: Returns all extraction and mathematical balance issues that require credit officer verification.

---

## 6. Export Endpoints

### `GET /api/v1/statements/{statement_id}/export/summary`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `ExportSummary`
- **Description**: Evaluates classification statistics, distinct calendar months, and counts unverified AI classifications before export.

### `POST /api/v1/statements/{statement_id}/export`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `ExportRequest` (`format`: `xlsx`|`csv`|`xlsx_audit`)
- **Response Schema**: `ExportResponse` (`downloadUrl`, `fileName`)
- **Description**: Triggers export packaging and returns a download link incorporating temporary JWT tokens.

### `GET /api/v1/statements/{statement_id}/download`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `format` (str), `token` (str)
- **Response Schema**: Binary file stream
- **Description**: Downloads the statement in Excel (`xlsx` / `xlsx_audit`) or `csv` format. Authenticates via standard headers or query parameter token.

---

## 7. Classification Endpoints

### `POST /api/v1/statements/{statement_id}/classify`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"statementId": statement_id}`
- **Description**: Starts transaction classification pipeline in a background worker.

### `GET /api/v1/statements/{statement_id}/classify/status`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"status": str, "progress": int, "successCount": int, "failedCount": int}`
- **Description**: Retrieves the status of the classification pipeline run.

### `PATCH /api/v1/statements/{statement_id}/classify/{tx_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: JSON payload containing `category` (str) and `third_party` (str)
- **Response Schema**: `{"success": true}`
- **Description**: Overrides a transaction's category classification.

### `POST /api/v1/statements/{statement_id}/classify/{tx_id}/confirm`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true}`
- **Description**: Marks a classification as verified by a broker.

### `POST /api/v1/statements/{statement_id}/classify/confirm-bulk`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: JSON list containing `tx_ids` (List[str])
- **Response Schema**: `{"success": true, "count": int}`
- **Description**: Marks multiple classifications as verified.

### `DELETE /api/v1/statements/{statement_id}/classify/{tx_id}/override`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"success": true}`
- **Description**: Resets a transaction classification back to its original pipeline-assigned value.

### `POST /api/v1/classify/upload-excel`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: Multipart form data with key `file` (Excel workbook)
- **Response Schema**: `{"statementId": statement_id}`
- **Description**: Ingests a pre-extracted transaction list from an Excel workbook and starts background classification.

---

## 8. Overwatch Observability Endpoints

These read-only endpoints are exposed from the `overwatch_router` component.

### `GET /api/v1/overwatch/events`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `document_id` (str), `document_name` (str), `log_level` (str), `stage` (str), `from_time` (str), `to_time` (str), `page` (int), `page_size` (int)
- **Response Schema**: `{"items": List[dict], "total": int, "page": int, "page_size": int}`
- **Description**: Queries system observability events from the SQLite WAL store.

### `GET /api/v1/overwatch/documents`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Query Params**: `from_time` (str), `to_time` (str), `has_errors` (bool), `has_warnings` (bool), `username` (str), `page` (int), `page_size` (int)
- **Response Schema**: `{"items": List[dict], "total": int, "page": int, "page_size": int}`
- **Description**: Lists document-level processing health summaries.

### `GET /api/v1/overwatch/documents/{document_id}/summary`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: Detailed document health metrics, runtime latency, and stage checks.
- **Description**: Returns the observability details for a single document. Returns `404` if the document is not found.

---

## 9. History Endpoints

### `GET /api/v1/history/statements`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `List[HistoryRow]` (`statementId`, `fileName`, `status`, `uploadedAt`, `accuracy`, `txCount`, `flaggedCount`)
- **Description**: Lists all statements ever uploaded to the system.

### `POST /api/v1/history/statements/{statement_id}/reopen`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `{"status": "success"}`
- **Description**: Reopens a finalized statement so that users can make additional edits.

### `POST /api/v1/history/statements/{statement_id}/duplicate`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `UploadInitResponse`
- **Description**: Clones an existing statement into a new statement ID to allow testing alternative layout rules.

### `DELETE /api/v1/history/statements/{statement_id}`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `None`
- **Description**: Deletes a statement, removes its data folder from disk, and removes associated database audit records.

---

## 10. Administration & Settings Endpoints

### `GET /api/v1/settings`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Response Schema**: `AppSettings`
- **Description**: Returns the active settings (`ocrEnabled`, `confidenceThreshold`, `autoExportEnabled`, `extractLast3Months`).

### `PATCH /api/v1/settings`
- **Auth Required**: Yes (`tester` | `manager` | `admin`)
- **Request Body**: `AppSettings` fields (optional)
- **Response Schema**: `AppSettings`
- **Description**: Modifies settings fields and flushes them to `data/settings.json`.

### `GET /api/v1/admin/audit-logs`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: JSON list of database audit logs
- **Description**: Lists system audit log table records for security monitoring.

### `GET /api/v1/admin/overwatch/insights`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: Overwatch analytics metrics (overall throughput, error rates, average latency per stage)
- **Description**: Returns analytics data on backend pipeline performance.

### `GET /api/v1/admin/uploads/pdfs`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `List[str]`
- **Description**: Lists file names stored in the filesystem uploads folder.

### `GET /api/v1/admin/uploads/pdfs-runtime`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `List[str]`
- **Description**: Scans the database and reports PDF files active in memory cache.

### `GET /api/v1/admin/overwatch/logs`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: Text stream of raw stdout log entries
- **Description**: Returns the log output stream.

### `GET /api/v1/admin/overwatch/export`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: CSV stream
- **Description**: Exports all database audit logs and overwatch logs in a single CSV file.

### `POST /api/v1/admin/overwatch/email-report`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: `OverwatchEmailRequest` (`email`: comma-separated recipients)
- **Response Schema**: Status message (`sent` | `simulated`)
- **Description**: Emails system log reports. Generates simulated emails inside `data/simulated_emails/` if no SMTP credentials are configured.

### `GET /api/v1/admin/categories`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `List[CategoryDict]`
- **Description**: Lists classification categories in the DB.

### `POST /api/v1/admin/categories`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: Category creation fields
- **Response Schema**: Category dictionary
- **Description**: Inserts a classification category into the database.

### `PATCH /api/v1/admin/categories/{category_id}`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: Category fields
- **Response Schema**: Category dictionary
- **Description**: Updates category details.

### `DELETE /api/v1/admin/categories/{category_id}`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: Status message
- **Description**: Deletes a classification category and cascades updates.

### `GET /api/v1/admin/rules`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `List[RuleDict]`
- **Description**: Lists all active database classification rules.

### `POST /api/v1/admin/rules`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: Rule creation fields
- **Response Schema**: Rule dictionary
- **Description**: Creates a new classification rule.

### `PATCH /api/v1/admin/rules/{rule_id}`
- **Auth Required**: Yes (`admin` only)
- **Request Body**: Rule fields
- **Response Schema**: Rule dictionary
- **Description**: Modifies classification rule fields.

### `DELETE /api/v1/admin/rules/{rule_id}`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: Status message
- **Description**: Deletes a classification rule in the database.

### `GET /api/v1/admin/llm-status`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `{"api_configured": bool, "latency_ms": float}`
- **Description**: Tests connectivity to the Google Gemini API.

### `POST /api/v1/admin/reset-pipeline`
- **Auth Required**: Yes (`admin` only)
- **Response Schema**: `{"status": "reset"}`
- **Description**: Clear in-memory caches, database tables, rules, and resets the server state.

---

## 11. Health Endpoints

### `GET /health`
- **Auth Required**: No
- **Response Schema**: `{"status": "ok", "version": "1.0.0", "database": "connected"}`
- **Description**: Endpoint used for cloud container health checks.

### `GET /`
- **Auth Required**: No
- **Response Schema**: Redirect
- **Description**: Redirects root visitors to `/docs` (FastAPI Swagger interface) or returns simple welcome messages depending on deployment environment settings.