project-bootstrap/USAGE.md

# Bootstrap Usage Guide

## Creating a New Project

### Basic Usage

```bash
./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

```bash
./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

```bash
cd my-awesome-project
```

### Step 2: Choose Your Development Method

#### Option A: Docker Compose (Recommended for Full Stack)

```bash
# 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:**
```bash
cd backend
cp .env.example .env
# Edit .env as needed
uv sync
uv run uvicorn app.main:app --reload
```

**Frontend:**
```bash
cd frontend
cp .env.example .env
# Edit .env as needed
npm install
npm start
```

**Database (if needed):**
```bash
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:**
```bash
cd backend
uv run pytest --cov=app --cov-report=term-missing
```

**Frontend:**
```bash
cd frontend
npm test
```

### Step 5: Code Quality Checks

**Lint:**
```bash
bash scripts/utils/lint-backend.sh
bash scripts/utils/lint-frontend.sh
```

**Format:**
```bash
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

```bash
# 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:**
```bash
cd backend
uv sync --upgrade
```

**Frontend:**
```bash
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:

```bash
# Find process
lsof -i :8000

# Kill process
kill -9 <PID>
```

Or modify ports in `deploy/compose.yml`.

### Permission Issues

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

### Docker Issues

```bash
# Clean Docker system
docker system prune -a

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

### Python/Node Issues

**Backend:**
```bash
cd backend
rm -rf .venv
uv sync
```

**Frontend:**
```bash
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

```bash
# 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
   bash scripts/ci/backend-test.sh
   bash scripts/ci/frontend-test.sh
   ```

2. **Format code before committing**
   ```bash
   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