# Project Bootstrap

A comprehensive bootstrap script for creating monorepo projects with FastAPI backend and React frontend, based on the coding standards from [coding-agent-rules](https://git.prettyhefty.com/Bill/coding-agent-rules).

## Features

- **Monorepo Structure** - Organized layout with backend, frontend, deployment, and scripts
- **FastAPI Backend** - Python 3.11+ with modern tooling (uv, ruff, mypy)
- **React Frontend** - TypeScript-based with ESLint, Prettier, and Jest
- **Docker Support** - Complete Docker Compose setup for local development
- **CI/CD Ready** - Gitea Actions workflows included
- **Testing** - 100% backend coverage requirement, 90%+ frontend coverage
- **Scripts** - Development and CI scripts for common tasks
- **Documentation** - Comprehensive docs for API, architecture, and user guide

## Quick Start

### Create a New Project

```bash
./bootstrap.sh my-new-project
```

This will create a complete project structure with all necessary files and configurations.

### Options

- `--no-git` - Skip git repository initialization

Example:
```bash
./bootstrap.sh my-project --no-git
```

## Project Structure

The bootstrap creates the following structure:

```
my-new-project/
├── README.md                    # Project overview and setup
├── LICENSE                      # MIT License
├── .gitignore                   # Git ignore rules
├── deploy/                      # Deployment configurations
│   ├── compose.yml             # Docker Compose file
│   ├── .env.example            # Environment variables
│   ├── docker/                 # Dockerfiles
│   │   ├── backend.Dockerfile
│   │   ├── frontend.Dockerfile
│   │   └── README.md
│   └── README.md
├── scripts/                     # Shared scripts
│   ├── ci/                     # CI scripts
│   │   ├── backend-test.sh
│   │   └── frontend-test.sh
│   ├── dev/                    # Development scripts
│   │   ├── start-backend.sh
│   │   ├── start-frontend.sh
│   │   ├── start-database.sh
│   │   └── reset-database.sh
│   └── utils/                  # Utility scripts
│       ├── lint-backend.sh
│       ├── lint-frontend.sh
│       └── format-all.sh
├── backend/                     # FastAPI backend
│   ├── pyproject.toml          # Python dependencies
│   ├── .env.example
│   ├── app/
│   │   ├── main.py             # FastAPI entry point
│   │   ├── api/                # API routes
│   │   ├── core/               # Core functionality
│   │   ├── db/                 # Database models
│   │   ├── services/           # Business logic
│   │   └── schemas/            # Pydantic schemas
│   └── tests/                  # Backend tests
│       ├── conftest.py
│       ├── unit/
│       └── integration/
├── frontend/                    # React frontend
│   ├── package.json            # Node dependencies
│   ├── tsconfig.json           # TypeScript config
│   ├── .env.example
│   ├── public/
│   ├── src/
│   │   ├── index.tsx
│   │   ├── App.tsx
│   │   ├── components/         # React components
│   │   ├── pages/              # Page components
│   │   ├── services/           # API services
│   │   ├── store/              # State management
│   │   ├── utils/              # Utilities
│   │   └── styles/             # CSS/SCSS
│   └── tests/                  # Frontend tests
├── docs/                        # Documentation
│   ├── api/                    # API documentation
│   ├── architecture/           # Architecture docs
│   └── user-guide/             # User guide
└── .gitea/                      # CI/CD workflows
    └── workflows/
        ├── backend-ci.yml
        └── frontend-ci.yml
```

## Tech Stack

### Backend
- **Python 3.11+**
- **FastAPI** - Modern web framework
- **Pydantic v2** - Data validation
- **uv** - Fast Python package manager
- **ruff** - Linting and formatting
- **mypy** - Type checking
- **pytest** - Testing framework

### Frontend
- **React 18**
- **TypeScript** - Type safety
- **Axios** - HTTP client
- **ESLint** - Linting
- **Prettier** - Code formatting
- **Jest** - Testing framework

### DevOps
- **Docker & Docker Compose**
- **Gitea Actions** - CI/CD
- **PostgreSQL** - Database

## Usage After Bootstrap

### 1. Navigate to Your Project

```bash
cd my-new-project
```

### 2. Start with Docker Compose (Recommended)

```bash
docker compose -f deploy/compose.yml up
```

Access:
- Frontend: http://localhost:3000
- Backend: http://localhost:8000
- API Docs: http://localhost:8000/docs

### 3. Or Start Services Individually

#### Backend
```bash
cd backend
cp .env.example .env
uv sync
uv run uvicorn app.main:app --reload
```

#### Frontend
```bash
cd frontend
cp .env.example .env
npm install
npm start
```

### 4. Run Tests

```bash
# Backend
cd backend
uv run pytest --cov=app

# Frontend
cd frontend
npm test
```

### 5. Code Quality

```bash
# Lint all code
bash scripts/utils/lint-backend.sh
bash scripts/utils/lint-frontend.sh

# Format all code
bash scripts/utils/format-all.sh
```

## Coding Standards

This bootstrap follows the coding standards defined in:
https://git.prettyhefty.com/Bill/coding-agent-rules

Key principles:
- **Modular monorepo layout** - Clear separation of concerns
- **100% backend test coverage** - Required for all backend code
- **90%+ frontend test coverage** - High quality frontend code
- **Type safety** - TypeScript for frontend, mypy for backend
- **Consistent formatting** - ruff for Python, Prettier for TypeScript
- **CI/CD ready** - Automated testing and linting

## Customization

After creating your project, you should:

1. Update `README.md` with your project details
2. Modify `LICENSE` with your information
3. Update `package.json` and `pyproject.toml` with your project name
4. Configure environment variables in `.env` files
5. Add your specific business logic and features

## Requirements

- **Bash** - For running the bootstrap script
- **Git** - For version control (optional with `--no-git`)
- **Docker & Docker Compose** - For containerized development
- **Python 3.11+** - For backend development
- **Node.js 20 LTS** - For frontend development
- **uv** - Python package manager ([install](https://github.com/astral-sh/uv))

## Contributing

Contributions are welcome! Please ensure any changes maintain compatibility with the coding standards.

## License

MIT License - See LICENSE file for details

## References

- [Coding Agent Rules](https://git.prettyhefty.com/Bill/coding-agent-rules)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [React Documentation](https://react.dev/)
- [uv Documentation](https://github.com/astral-sh/uv)