147 lines
5.1 KiB
Markdown
147 lines
5.1 KiB
Markdown
# StoryCove Documentation
|
|
|
|
Welcome to the StoryCove documentation! This directory contains comprehensive documentation for the StoryCove application.
|
|
|
|
## 📚 Documentation Files
|
|
|
|
### **[API Documentation](API.md)**
|
|
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](DATA_MODEL.md)**
|
|
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](openapi.yaml)**
|
|
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](API.md) for endpoint details
|
|
2. Reference [Data Model](DATA_MODEL.md) for database understanding
|
|
3. Use [OpenAPI spec](openapi.yaml) for testing and integration
|
|
4. See main [README](../README.md) for setup instructions
|
|
|
|
### **For API Integration**
|
|
1. Review authentication flow in [API docs](API.md)
|
|
2. Import [OpenAPI spec](openapi.yaml) 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](DATA_MODEL.md) 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](../README.md) for deployment instructions
|
|
2. Use environment configuration examples
|
|
3. Review backup strategies in [Data Model](DATA_MODEL.md)
|
|
4. Monitor API health using documented endpoints
|
|
|
|
## 🔗 External Resources
|
|
|
|
### **Related Documentation**
|
|
- **[Main README](../README.md)**: Project overview, setup, and deployment
|
|
- **[Technical Specification](../storycove-spec.md)**: Comprehensive technical specification
|
|
- **Environment Files**: `.env.example`, `.env.development`, `.env.production`
|
|
|
|
### **Technology Documentation**
|
|
- **[Spring Boot](https://spring.io/projects/spring-boot)**: Backend framework
|
|
- **[Next.js](https://nextjs.org/)**: Frontend framework
|
|
- **[PostgreSQL](https://www.postgresql.org/docs/)**: Database system
|
|
- **[Typesense](https://typesense.org/docs/)**: Search engine
|
|
- **[Docker](https://docs.docker.com/)**: 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](API.md) and [openapi.yaml](openapi.yaml)
|
|
2. **Database Changes**: Update [DATA_MODEL.md](DATA_MODEL.md)
|
|
3. **Feature Changes**: Update main [README](../README.md) 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. |