Files

Bill 8dd4f0ca63 Initial commit: Complete project-bootstrap tool

- 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

2025-10-15 21:34:08 -04:00

2.9 KiB

Raw Blame History

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

Clone the repository:

git clone <repository-url>
cd <project-name>

Start all services:

docker compose -f deploy/compose.yml up

Access the application:
- Frontend: http://localhost:3000
- Backend API: http://localhost:8000
- API Documentation: http://localhost:8000/docs

Local Development

Backend Development

Navigate to backend directory:
```
cd backend
```
Copy environment file:
```
cp .env.example .env
```
Install dependencies:
```
uv sync
```
Start the development server:
```
uv run uvicorn app.main:app --reload
```

Or use the convenience script:

bash scripts/dev/start-backend.sh

Frontend Development

Navigate to frontend directory:
```
cd frontend
```
Copy environment file:
```
cp .env.example .env
```
Install dependencies:
```
npm install
```
Start the development server:
```
npm start
```

Or use the convenience script:

bash scripts/dev/start-frontend.sh

Testing

Backend Tests

cd backend
uv run pytest --cov=app

Frontend Tests

cd frontend
npm test

Code Quality

Linting

# Backend
bash scripts/utils/lint-backend.sh

# Frontend
bash scripts/utils/lint-frontend.sh

Formatting

bash scripts/utils/format-all.sh

Common Tasks

Adding a New API Endpoint

Create endpoint in backend/app/api/
Add business logic in backend/app/services/
Define schemas in backend/app/schemas/
Write tests in backend/tests/

Adding a New Frontend Component

Create component in frontend/src/components/
Add styles in frontend/src/styles/
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:

# Find process using the port
lsof -i :8000  # or :3000 for frontend

# Kill the process
kill -9 <PID>

Docker Issues

# Clean up Docker resources
docker compose -f deploy/compose.yml down
docker system prune -a

Dependency Issues

# 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

2.9 KiB Raw Blame History