Documents Overview

​

Introduction

​

Key Features

​

Document Management

• Create, read, update, and delete document records
• Store document metadata including title, description, and dates
• Associate documents with specific communities
• Track document uploaders for access control

​

File Upload

• Upload files up to 20 MB
• Organized file storage by community, category, and resident
• Automatic path sanitization and validation
• Support for multiple file types

​

Access Control

• Role-based authorization (ADMIN_COMPANY, SYSTEM_ADMIN)
• Document download permissions based on uploader or community admin role
• Secure file path handling to prevent path traversal attacks

​

Document Organization

• Filter documents by community
• Categorize documents (e.g., general, contracts, reports)
• Associate documents with specific residents
• Track creation dates and metadata

​

Document Structure

​

File Storage Organization

uploads/documents/{communityId}/{category}/{residentId}/{fileName}

• communityId: The community’s unique identifier
• category: Document category (defaults to “general” if not provided)
• residentId: Resident’s unique identifier (defaults to “general” if not provided)
• fileName: Sanitized file name

​

Authorization

• ADMIN_COMPANY: Company administrator with access to their community’s documents
• SYSTEM_ADMIN: System administrator with full access

• Company admins can download documents from their community
• Users can download documents they uploaded
• Other users are forbidden from downloading documents

​

Common Use Cases

​

Upload and Create Document

1. Upload a file using POST /api/Documents/upload
2. Receive the RelativePath in the response
3. Create a document record using POST /api/Documents with the relative path as UrlDoc

​

Download Document

1. Retrieve document metadata using GET /api/Documents/{id}
2. Download the file using GET /api/Documents/{id}/download
3. The system verifies permissions before serving the file

​

Community Documents

1. Query documents for a specific community using GET /api/Documents/community/{communityId}
2. Returns all documents associated with that community

​

Error Handling

• 200 OK: Successful request
• 201 Created: Document successfully created
• 204 No Content: Document successfully deleted
• 400 Bad Request: Invalid request data or missing required fields
• 401 Unauthorized: Authentication required
• 403 Forbidden: User lacks permission to access the resource
• 404 Not Found: Document not found
• 500 Internal Server Error: Server error during file operations

​

File Size Limits

• Maximum upload size: 20 MB
• Applies to both /api/Documents/upload and /api/File/upload endpoints
• Configured via RequestSizeLimit and RequestFormLimits attributes

​

Next Steps