Bill
8dd4f0ca63
- 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
234 lines
6.9 KiB
Markdown
234 lines
6.9 KiB
Markdown
# 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)
|