Initial commit: Complete project-bootstrap tool
- 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
This commit is contained in:
233
README.md
Normal file
233
README.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user