Expand README with detailed documentation on project structure, backend features, development workflows, and deployment instructions.

2025-10-29 22:30:48 +01:00
parent 6d34f81912
commit 778da09a42
1 changed files with 201 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -57,3 +57,204 @@ make dev
 - API Docs: http://localhost:8000/docs

 ## Project Structure
+
+```
+fast-next-template/
+├── backend/                 # FastAPI backend
+│   ├── app/
+│   │   ├── alembic/        # Database migrations
+│   │   ├── api/            # API routes and dependencies
+│   │   ├── core/           # Core functionality (auth, config, db)
+│   │   ├── crud/           # Database CRUD operations
+│   │   ├── models/         # SQLAlchemy models
+│   │   ├── schemas/        # Pydantic schemas
+│   │   ├── services/       # Business logic services
+│   │   ├── utils/          # Utility functions
+│   │   ├── init_db.py      # Database initialization script
+│   │   └── main.py         # FastAPI application entry
+│   ├── tests/              # Comprehensive test suite
+│   ├── migrate.py          # Migration helper CLI
+│   ├── requirements.txt    # Python dependencies
+│   └── Dockerfile          # Multi-stage container build
+├── frontend/               # Next.js frontend
+│   ├── src/
+│   │   ├── app/           # Next.js app router
+│   │   └── components/    # React components
+│   ├── public/            # Static assets
+│   └── Dockerfile         # Next.js container build
+├── docker-compose.yml      # Production compose configuration
+├── docker-compose.dev.yml  # Development compose configuration
+├── docker-compose.deploy.yml # Deployment with pre-built images
+└── .env.template          # Environment variables template
+```
+
+## Backend Features
+
+### Authentication System
+- **JWT-based authentication** with access and refresh tokens
+- **User management** with email/password authentication
+- **Password hashing** using bcrypt
+- **Token expiration** handling (access: 1 day, refresh: 60 days)
+- **Optional authentication** support for public/private endpoints
+- **Superuser** authorization support
+
+### Database Management
+- **PostgreSQL** with optimized connection pooling
+- **Alembic migrations** with auto-generation support
+- **Migration CLI helper** (`migrate.py`) for easy database management:
+  ```bash
+  python migrate.py generate "add users table"  # Generate migration
+  python migrate.py apply                        # Apply migrations
+  python migrate.py list                         # List all migrations
+  python migrate.py current                      # Show current revision
+  python migrate.py check                        # Check DB connection
+  python migrate.py auto "message"               # Generate and apply
+  ```
+- **Automatic database initialization** with first superuser creation
+
+### Testing Infrastructure
+- **92 comprehensive tests** covering all core functionality
+- **SQLite in-memory** database for fast test execution
+- **Auth test utilities** for easy endpoint testing
+- **Mocking support** for external dependencies
+- **Test fixtures** for common scenarios
+
+### Security Utilities
+- **Upload token system** for secure file operations
+- **HMAC-based signing** for token validation
+- **Time-limited tokens** with expiration
+- **Nonce support** to prevent token reuse
+
+## Development
+
+### Running Tests
+
+```bash
+# Backend tests
+cd backend
+source .venv/bin/activate
+pytest tests/ -v
+
+# With coverage
+pytest tests/ --cov=app --cov-report=html
+```
+
+### Database Migrations
+
+```bash
+# Using the migration helper
+python migrate.py generate "your migration message"
+python migrate.py apply
+
+# Or using alembic directly
+alembic revision --autogenerate -m "your message"
+alembic upgrade head
+```
+
+### First Superuser
+
+The backend automatically creates a superuser on initialization. Configure via environment variables:
+
+```bash
+FIRST_SUPERUSER_EMAIL=admin@example.com
+FIRST_SUPERUSER_PASSWORD=admin123
+```
+
+If not configured, defaults to `admin@example.com` / `admin123`.
+
+## Deployment
+
+### Option 1: Build and Deploy Locally
+
+For production with local builds:
+
+```bash
+docker-compose up -d
+```
+
+### Option 2: Deploy with Pre-built Images
+
+For deployment using images from a container registry:
+
+1. Build and push your images:
+```bash
+# Build images
+docker-compose build
+
+# Tag for your registry
+docker tag fast-next-template-backend:latest your-registry/your-project-backend:latest
+docker tag fast-next-template-frontend:latest your-registry/your-project-frontend:latest
+
+# Push to registry
+docker push your-registry/your-project-backend:latest
+docker push your-registry/your-project-frontend:latest
+```
+
+2. Update `docker-compose.deploy.yml` with your image references:
+```yaml
+services:
+  backend:
+    image: your-registry/your-project-backend:latest
+  frontend:
+    image: your-registry/your-project-frontend:latest
+```
+
+3. Deploy:
+```bash
+docker-compose -f docker-compose.deploy.yml up -d
+```
+
+### Environment Variables
+
+Create a `.env` file based on `.env.template`:
+
+```bash
+# Project
+PROJECT_NAME=MyApp
+VERSION=1.0.0
+
+# Database
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=your-secure-password
+POSTGRES_DB=app
+POSTGRES_HOST=db
+POSTGRES_PORT=5432
+
+# Backend
+BACKEND_PORT=8000
+SECRET_KEY=your-secret-key-change-this-in-production
+ENVIRONMENT=production
+DEBUG=false
+BACKEND_CORS_ORIGINS=["http://localhost:3000"]
+
+# First Superuser
+FIRST_SUPERUSER_EMAIL=admin@example.com
+FIRST_SUPERUSER_PASSWORD=admin123
+
+# Frontend
+NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
+```
+
+## API Documentation
+
+Once the backend is running, visit:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+## Available Endpoints
+
+### Authentication
+- `POST /api/v1/auth/register` - User registration
+- `POST /api/v1/auth/login` - User login (JSON)
+- `POST /api/v1/auth/login/oauth` - OAuth2-compatible login
+- `POST /api/v1/auth/refresh` - Refresh access token
+- `POST /api/v1/auth/change-password` - Change password
+- `GET /api/v1/auth/me` - Get current user info
+
+## Contributing
+
+This is a template project. Feel free to fork and customize for your needs.
+
+## License
+
+MIT License - feel free to use this template for your projects.