Server Actions & APIs
Relevant source files
The following files were used as context for generating this wiki page:
- app/(chat)/api/document/route.ts/api/document/route.ts)
- app/(chat)/api/files/upload/route.test.ts/api/files/upload/route.test.ts)
- app/(chat)/lv/import-actions.ts/lv/import-actions.ts)
- lib/ai/tools/create-document.ts
- lib/ai/tools/update-document.ts
- tests/e2e/api.test.ts
Server Actions and API routes manage data persistence, file processing, and AI tool execution in the LV.AI project. These components handle sensitive operations including GAEB file imports, document versioning, and secure file uploads to Vercel Blob or local storage.
Sources: app/(chat)/api/document/route.ts, app/(chat)/lv/import-actions.ts, app/(chat)/api/files/upload/route.test.ts
Document Management API
The /api/document endpoint handles the lifecycle of AI-generated artifacts such as text, code, sheets, and images. It supports versioning by allowing users to retrieve historical states or delete specific versions based on timestamps.
API Endpoints
| Method | Description | Parameters |
|---|---|---|
GET | Retrieves documents by ID. | id (string) |
POST | Saves a new document version or updates an existing one via manual edit. | id (query), content, title, kind, isManualEdit (body) |
DELETE | Removes document versions after a specific timestamp. | id (string), timestamp (string) |
Sources: app/(chat)/api/document/route.ts:18-124
Data Flow: Manual vs. AI Updates
The POST handler distinguishes between manual user edits and AI-generated updates. Manual edits trigger a direct content update, while AI updates typically result in a new document entry to maintain version history.
LV Import Server Actions
The importLvFileAction handles the ingestion of GAEB DA XML (X81-X89) and tabular LV files. It processes uploaded files, parses their content, and populates the database with structured LV documents and positions.
Import Procedure
- Authentication: The action verifies the user session before processing.
- Download: It fetches the file from the provided
fileUrl. - Parsing: The
parseLvContentutility identifies the format and extracts positions. - Persistence: It creates an
LvDocumentand iterates through positions to save them. - Normalization: The action normalizes Outline Numbers (OZ), converting double dots (..) to single dots (.).
Sources: app/(chat)/lv/import-actions.ts:52-167
Import Result Structure
| Field | Type | Description |
|---|---|---|
documentId | string | The UUID of the created LV document. |
format | string | Detected format: gaeb-xml, lv-text, or unknown. |
positionCount | number | Total successfully imported positions. |
warnings | string[] | List of issues encountered (e.g., skipped positions). |
Sources: app/(chat)/lv/import-actions.ts:44-50
AI Tool Execution
AI tools provide a bridge between the Large Language Model and server-side logic. The project implements specific tools for creating and updating artifacts within the chat interface.
Document Tools
- createDocument: Generates a new artifact. It requires a
titleand akind(code, text, or sheet). It generates a unique ID and writes metadata to the data stream. - updateDocument: Performs a full rewrite of an existing artifact. It validates that the requesting user owns the document before invoking the specific artifact handler.
Sources: lib/ai/tools/create-document.ts:15-84, lib/ai/tools/update-document.ts:16-79
File Upload API
The /api/files/upload endpoint supports multi-destination storage. It checks for a BLOB_READ_WRITE_TOKEN to determine whether to use Vercel Blob storage or fall back to local filesystem storage in the /uploads/lv-ai/ directory.
Upload Constraints
- Size Limit: Files must not exceed 20MB.
- Allowed Types: Validated against specific AVA-relevant extensions (PDF, GAEB XML, Excel, Word, CSV, Images).
- Auth: Requires a valid user session.
Sources: app/(chat)/api/files/upload/route.test.ts:60-120
API Integration Testing
End-to-end tests verify the integration between the frontend and the Chat API. These tests ensure that messages result in AI responses and that the UI state (such as input clearing and stop buttons) behaves correctly during active generation.
- Response Validation: Checks if the assistant message is visible and contains content.
- Redirect Logic: Verifies that new chats redirect to
/chat/:id. - Error Handling: Simulates 500 status codes to ensure the UI displays error messages gracefully.
Sources: tests/e2e/api.test.ts:6-66
The Server Actions and APIs form the backbone of LV.AI's collaborative environment, enabling complex GAEB data processing while maintaining strict document versioning and security controls.