Bill
8dd4f0ca63
- Bootstrap script for creating monorepo projects - FastAPI backend templates with uv, ruff, mypy, pytest - React frontend templates with TypeScript, ESLint, Prettier - Docker Compose setup with backend, frontend, and database - 9 development and CI scripts - Gitea Actions CI/CD workflows - Comprehensive documentation (8 files) - 45 template files for complete project structure - Automated verification script (all tests pass) - Based on coding-agent-rules standards
187 lines
2.9 KiB
Markdown
187 lines
2.9 KiB
Markdown
# User Guide
|
|
|
|
## Getting Started
|
|
|
|
This guide will help you get started with the application.
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
Before you begin, ensure you have the following installed:
|
|
|
|
- Docker and Docker Compose
|
|
- Python 3.11+ (for local backend development)
|
|
- Node.js 20 LTS (for local frontend development)
|
|
- uv (Python package manager)
|
|
|
|
### Quick Start with Docker
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd <project-name>
|
|
```
|
|
|
|
2. Start all services:
|
|
```bash
|
|
docker compose -f deploy/compose.yml up
|
|
```
|
|
|
|
3. Access the application:
|
|
- Frontend: http://localhost:3000
|
|
- Backend API: http://localhost:8000
|
|
- API Documentation: http://localhost:8000/docs
|
|
|
|
## Local Development
|
|
|
|
### Backend Development
|
|
|
|
1. Navigate to backend directory:
|
|
```bash
|
|
cd backend
|
|
```
|
|
|
|
2. Copy environment file:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
3. Install dependencies:
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
4. Start the development server:
|
|
```bash
|
|
uv run uvicorn app.main:app --reload
|
|
```
|
|
|
|
Or use the convenience script:
|
|
```bash
|
|
bash scripts/dev/start-backend.sh
|
|
```
|
|
|
|
### Frontend Development
|
|
|
|
1. Navigate to frontend directory:
|
|
```bash
|
|
cd frontend
|
|
```
|
|
|
|
2. Copy environment file:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
3. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
4. Start the development server:
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
Or use the convenience script:
|
|
```bash
|
|
bash scripts/dev/start-frontend.sh
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Backend Tests
|
|
|
|
```bash
|
|
cd backend
|
|
uv run pytest --cov=app
|
|
```
|
|
|
|
### Frontend Tests
|
|
|
|
```bash
|
|
cd frontend
|
|
npm test
|
|
```
|
|
|
|
## Code Quality
|
|
|
|
### Linting
|
|
|
|
```bash
|
|
# Backend
|
|
bash scripts/utils/lint-backend.sh
|
|
|
|
# Frontend
|
|
bash scripts/utils/lint-frontend.sh
|
|
```
|
|
|
|
### Formatting
|
|
|
|
```bash
|
|
bash scripts/utils/format-all.sh
|
|
```
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New API Endpoint
|
|
|
|
1. Create endpoint in `backend/app/api/`
|
|
2. Add business logic in `backend/app/services/`
|
|
3. Define schemas in `backend/app/schemas/`
|
|
4. Write tests in `backend/tests/`
|
|
|
|
### Adding a New Frontend Component
|
|
|
|
1. Create component in `frontend/src/components/`
|
|
2. Add styles in `frontend/src/styles/`
|
|
3. Write tests in `frontend/tests/components/`
|
|
|
|
### Database Migrations
|
|
|
|
(Add database migration instructions when implemented)
|
|
|
|
## Troubleshooting
|
|
|
|
### Port Already in Use
|
|
|
|
If you get a "port already in use" error:
|
|
|
|
```bash
|
|
# Find process using the port
|
|
lsof -i :8000 # or :3000 for frontend
|
|
|
|
# Kill the process
|
|
kill -9 <PID>
|
|
```
|
|
|
|
### Docker Issues
|
|
|
|
```bash
|
|
# Clean up Docker resources
|
|
docker compose -f deploy/compose.yml down
|
|
docker system prune -a
|
|
```
|
|
|
|
### Dependency Issues
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend
|
|
rm -rf .venv
|
|
uv sync
|
|
|
|
# Frontend
|
|
cd frontend
|
|
rm -rf node_modules package-lock.json
|
|
npm install
|
|
```
|
|
|
|
## Support
|
|
|
|
For issues and questions:
|
|
- Check the documentation in `/docs`
|
|
- Review the API documentation at http://localhost:8000/docs
|
|
- Open an issue in the repository
|