storycove/docs/README.md

StoryCove Documentation

Welcome to the StoryCove documentation! This directory contains comprehensive documentation for the StoryCove application.

📚 Documentation Files

API Documentation

Complete REST API reference with detailed endpoint descriptions, request/response examples, authentication details, and error handling.

Contents:

• Authentication endpoints
• Story management (CRUD, search, images)
• Author management (profiles, avatars, URLs)
• Tag system (creation, autocomplete, statistics)
• Series management (organization, navigation)
• File upload/download (images, validation)
• Search and indexing (Typesense integration)
• Configuration endpoints
• Data Transfer Objects (DTOs)
• Error handling and status codes

Data Model Documentation

Detailed database schema documentation including entity relationships, constraints, indexes, and business rules.

Contents:

• Entity Relationship Diagram
• Detailed table specifications
• Field types and constraints
• Relationship mappings
• Performance considerations
• Backup and migration strategy

OpenAPI Specification

Machine-readable API specification in OpenAPI 3.0 format for API testing tools, code generation, and integration.

Usage:

• Import into Postman, Insomnia, or similar tools
• Generate client SDKs
• API documentation hosting (Swagger UI)
• Contract testing

🛠️ How to Use This Documentation

For Developers

1. Start with the API Documentation for endpoint details
2. Reference Data Model for database understanding
3. Use OpenAPI spec for testing and integration
4. See main README for setup instructions

For API Integration

1. Review authentication flow in API docs
2. Import OpenAPI spec into your API client
3. Test endpoints using the provided examples
4. Implement error handling based on documented responses

For Database Work

1. Study Data Model for schema understanding
2. Review relationship constraints and business rules
3. Use entity diagrams for system architecture planning
4. Follow migration guidelines for schema changes

For System Administration

1. Reference main README for deployment instructions
2. Use environment configuration examples
3. Review backup strategies in Data Model
4. Monitor API health using documented endpoints

🔗 External Resources

Related Documentation

• Main README: Project overview, setup, and deployment
• Technical Specification: Comprehensive technical specification
• Environment Files: .env.example, .env.development, .env.production

Technology Documentation

• Spring Boot: Backend framework
• Next.js: Frontend framework
• PostgreSQL: Database system
• Typesense: Search engine
• Docker: Containerization

📝 Documentation Standards

API Documentation

• All endpoints documented with examples
• Request/response schemas included
• Error scenarios covered
• Authentication requirements specified

Code Examples

• JSON examples use realistic data
• UUIDs formatted correctly
• Timestamps in ISO 8601 format
• Error responses include helpful messages

Data Model

• All tables and relationships documented
• Constraints and validation rules specified
• Performance implications noted
• Migration considerations included

🤝 Contributing to Documentation

When updating the application:

1. API Changes: Update API.md and openapi.yaml
2. Database Changes: Update DATA_MODEL.md
3. Feature Changes: Update main README features section
4. Deployment Changes: Update environment configuration examples

Documentation Checklist

• API endpoints documented with examples
• Database schema changes reflected
• OpenAPI specification updated
• Error handling documented
• Authentication requirements specified
• Performance implications noted
• Migration steps documented

📋 Quick Reference

Base URLs

• Development: http://localhost:6925/api
• Production: https://yourdomain.com/api

Authentication

• Method: JWT tokens via httpOnly cookies
• Login: POST /api/auth/login
• Token Expiry: 24 hours

Key Endpoints

• Stories: /api/stories
• Authors: /api/authors
• Tags: /api/tags
• Series: /api/series
• Search: /api/stories/search
• Files: /api/files

Common Response Codes

• 200: Success
• 201: Created
• 400: Bad Request
• 401: Unauthorized
• 404: Not Found
• 500: Server Error

This documentation is maintained alongside the codebase to ensure accuracy and completeness. For questions or clarifications, please refer to the appropriate documentation file or create an issue in the project repository.