project-bootstrap/USAGE.md

Bootstrap Usage Guide

Creating a New Project

Basic Usage

./bootstrap.sh my-awesome-project

This will:

1. Create the complete directory structure
2. Copy all template files
3. Create Python __init__.py files
4. Initialize a git repository
5. Make an initial commit

Without Git Initialization

./bootstrap.sh my-awesome-project --no-git

What Gets Created

Directory Structure

my-awesome-project/
├── backend/           # FastAPI backend
├── frontend/          # React frontend
├── deploy/            # Docker & deployment
├── scripts/           # Development & CI scripts
├── docs/              # Documentation
└── .gitea/            # CI workflows

Configuration Files

• Backend: pyproject.toml, .env.example
• Frontend: package.json, tsconfig.json, .eslintrc.json, .prettierrc.json
• Docker: compose.yml, Dockerfiles
• Git: .gitignore

Scripts

All scripts are executable and ready to use:

• scripts/dev/start-backend.sh - Start backend server
• scripts/dev/start-frontend.sh - Start frontend server
• scripts/dev/start-database.sh - Start database
• scripts/dev/reset-database.sh - Reset database
• scripts/utils/lint-backend.sh - Lint backend
• scripts/utils/lint-frontend.sh - Lint frontend
• scripts/utils/format-all.sh - Format all code
• scripts/ci/backend-test.sh - Run backend CI tests
• scripts/ci/frontend-test.sh - Run frontend CI tests

After Bootstrap

Step 1: Navigate to Your Project

cd my-awesome-project

Step 2: Choose Your Development Method

Option A: Docker Compose (Recommended for Full Stack)

# Start all services
docker compose -f deploy/compose.yml up

# Or in detached mode
docker compose -f deploy/compose.yml up -d

# View logs
docker compose -f deploy/compose.yml logs -f

# Stop services
docker compose -f deploy/compose.yml down

Option B: Local Development

Backend:

cd backend
cp .env.example .env
# Edit .env as needed
uv sync
uv run uvicorn app.main:app --reload

Frontend:

cd frontend
cp .env.example .env
# Edit .env as needed
npm install
npm start

Database (if needed):

bash scripts/dev/start-database.sh

Step 3: Verify Installation

Backend:

• API: http://localhost:8000
• Docs: http://localhost:8000/docs
• Health: http://localhost:8000/health

Frontend:

• App: http://localhost:3000

Step 4: Run Tests

Backend:

cd backend
uv run pytest --cov=app --cov-report=term-missing

Frontend:

cd frontend
npm test

Step 5: Code Quality Checks

Lint:

bash scripts/utils/lint-backend.sh
bash scripts/utils/lint-frontend.sh

Format:

bash scripts/utils/format-all.sh

Customization Checklist

After creating your project, customize these files:

Essential

• README.md - Update with your project details
• LICENSE - Add your name and year
• backend/pyproject.toml - Update name and description
• frontend/package.json - Update name and description
• backend/.env - Configure environment variables
• frontend/.env - Configure environment variables
• deploy/.env - Configure deployment variables

Optional

• docs/api/README.md - Document your API endpoints
• docs/architecture/README.md - Add architecture diagrams
• docs/user-guide/README.md - Write user documentation
• .gitea/workflows/ - Customize CI/CD workflows

Development Workflow

Adding a New Backend Endpoint

1. Create route 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/
5. Run tests: uv run pytest
6. Check coverage: Must be 100%

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/
4. Run tests: npm test
5. Check coverage: Should be ≥90%

Adding a Database Model

1. Create model in backend/app/db/models/
2. Update database session in backend/app/db/session.py
3. Add migration script (if using Alembic)
4. Write tests in backend/tests/unit/test_db/test_models/

Common Tasks

Reset Everything

# Stop all containers
docker compose -f deploy/compose.yml down

# Remove volumes
docker compose -f deploy/compose.yml down -v

# Clean up
rm -rf backend/.venv frontend/node_modules

# Start fresh
docker compose -f deploy/compose.yml up --build

Update Dependencies

Backend:

cd backend
uv sync --upgrade

Frontend:

cd frontend
npm update

View API Documentation

Start the backend and visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Troubleshooting

Port Conflicts

If ports 8000, 3000, or 5432 are in use:

# Find process
lsof -i :8000

# Kill process
kill -9 <PID>

Or modify ports in deploy/compose.yml.

Permission Issues

# Make scripts executable
chmod +x scripts/**/*.sh

Docker Issues

# Clean Docker system
docker system prune -a

# Rebuild containers
docker compose -f deploy/compose.yml up --build --force-recreate

Python/Node Issues

Backend:

cd backend
rm -rf .venv
uv sync

Frontend:

cd frontend
rm -rf node_modules package-lock.json
npm install

CI/CD

The project includes Gitea Actions workflows:

• .gitea/workflows/backend-ci.yml - Backend tests
• .gitea/workflows/frontend-ci.yml - Frontend tests

These run automatically on:

• Push to main/master/develop branches
• Pull requests to main/master/develop branches

Running CI Scripts Locally

# Backend CI
bash scripts/ci/backend-test.sh

# Frontend CI
bash scripts/ci/frontend-test.sh

Best Practices

1. Always run tests before committing

   bash scripts/ci/backend-test.sh
   bash scripts/ci/frontend-test.sh
   

2. Format code before committing

   bash scripts/utils/format-all.sh
   

3. Keep 100% backend test coverage

   • All new code must have tests
   • Coverage check is enforced in CI

4. Maintain ≥90% frontend test coverage

   • Test all components and services
   • Use Jest and React Testing Library

5. Follow the project structure

   • Keep files in their designated directories
   • Follow naming conventions

6. Document your changes

   • Update API documentation
   • Add comments for complex logic
   • Update CHANGELOG.md

Next Steps

1. Start building your features
2. Add database models and migrations
3. Implement authentication/authorization
4. Add more API endpoints
5. Build frontend components
6. Write comprehensive tests
7. Deploy to production

Support

For issues with the bootstrap:

• Check this guide
• Review the main README.md
• Check the coding-agent-rules repository

For project-specific issues:

• Review documentation in /docs
• Check API docs at http://localhost:8000/docs