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.

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

./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:

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

cd my-new-project

2. Start with Docker Compose (Recommended)

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

cd backend
cp .env.example .env
uv sync
uv run uvicorn app.main:app --reload

Frontend

cd frontend
cp .env.example .env
npm install
npm start

4. Run Tests

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

# Frontend
cd frontend
npm test

5. Code Quality

# 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)

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
• FastAPI Documentation
• React Documentation
• uv Documentation