forked from cardosofelipe/fast-next-template
Add comprehensive CONTRIBUTING and README documentation
- Introduced `CONTRIBUTING.md` to provide detailed guidelines for contributing, covering coding standards, testing, commit messages, and the pull request process. - Added a new `README.md` to document the project setup, features, tech stack, testing infrastructure, and deployment instructions. - Improved accessibility and structure of developer resources for better onboarding and collaboration.
This commit is contained in:
Felipe Cardoso
387
CONTRIBUTING.md
Normal file
387
CONTRIBUTING.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# Contributing to FastAPI + Next.js Template
|
||||
|
||||
First off, thank you for considering contributing to this project! 🎉
|
||||
|
||||
This template aims to be a rock-solid foundation for full-stack applications, and your contributions help make that possible.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Code of Conduct](#code-of-conduct)
|
||||
- [How Can I Contribute?](#how-can-i-contribute)
|
||||
- [Development Setup](#development-setup)
|
||||
- [Coding Standards](#coding-standards)
|
||||
- [Testing Guidelines](#testing-guidelines)
|
||||
- [Commit Messages](#commit-messages)
|
||||
- [Pull Request Process](#pull-request-process)
|
||||
|
||||
---
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
This project is committed to providing a welcoming and inclusive environment. We expect all contributors to:
|
||||
|
||||
- Be respectful and considerate
|
||||
- Welcome newcomers and help them learn
|
||||
- Focus on constructive criticism
|
||||
- Accept feedback gracefully
|
||||
- Prioritize the community's well-being
|
||||
|
||||
Unacceptable behavior includes harassment, trolling, insulting comments, and personal attacks.
|
||||
|
||||
---
|
||||
|
||||
## How Can I Contribute?
|
||||
|
||||
### Reporting Bugs
|
||||
|
||||
Found a bug? Help us fix it!
|
||||
|
||||
1. **Check existing issues** to avoid duplicates
|
||||
2. **Create a new issue** with:
|
||||
- Clear, descriptive title
|
||||
- Steps to reproduce
|
||||
- Expected vs. actual behavior
|
||||
- Environment details (OS, Python/Node version, etc.)
|
||||
- Screenshots/logs if applicable
|
||||
|
||||
### Suggesting Features
|
||||
|
||||
Have an idea for improvement?
|
||||
|
||||
1. **Check existing issues/discussions** first
|
||||
2. **Open a discussion** to gauge interest
|
||||
3. **Explain the use case** and benefits
|
||||
4. **Consider implementation complexity**
|
||||
|
||||
Remember: This is a *template*, not a full application. Features should be:
|
||||
- Broadly useful
|
||||
- Well-documented
|
||||
- Thoroughly tested
|
||||
- Maintainable long-term
|
||||
|
||||
### Improving Documentation
|
||||
|
||||
Documentation improvements are always welcome!
|
||||
|
||||
- Fix typos or unclear explanations
|
||||
- Add examples or diagrams
|
||||
- Expand on complex topics
|
||||
- Update outdated information
|
||||
- Translate documentation (future)
|
||||
|
||||
### Contributing Code
|
||||
|
||||
Ready to write some code? Awesome!
|
||||
|
||||
1. **Pick an issue** (or create one)
|
||||
2. **Comment** that you're working on it
|
||||
3. **Fork and branch** from `main`
|
||||
4. **Write code** following our standards
|
||||
5. **Add tests** (required for features)
|
||||
6. **Update docs** if needed
|
||||
7. **Submit a PR** with clear description
|
||||
|
||||
---
|
||||
|
||||
## Development Setup
|
||||
|
||||
### Backend Development
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Setup virtual environment
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Setup environment
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Run tests
|
||||
IS_TEST=True pytest
|
||||
|
||||
# Start dev server
|
||||
uvicorn app.main:app --reload
|
||||
```
|
||||
|
||||
### Frontend Development
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Setup environment
|
||||
cp .env.local.example .env.local
|
||||
|
||||
# Generate API client
|
||||
npm run generate:api
|
||||
|
||||
# Run tests
|
||||
npm test
|
||||
npm run test:e2e:ui
|
||||
|
||||
# Start dev server
|
||||
npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Coding Standards
|
||||
|
||||
### Backend (Python)
|
||||
|
||||
- **Style**: Follow PEP 8
|
||||
- **Type hints**: Use type annotations
|
||||
- **Async**: Use async/await for I/O operations
|
||||
- **Documentation**: Docstrings for all public functions/classes
|
||||
- **Error handling**: Use custom exceptions appropriately
|
||||
- **Security**: Never trust user input, validate everything
|
||||
|
||||
Example:
|
||||
```python
|
||||
async def get_user_by_email(
|
||||
db: AsyncSession,
|
||||
*,
|
||||
email: str
|
||||
) -> Optional[User]:
|
||||
"""
|
||||
Get user by email address.
|
||||
|
||||
Args:
|
||||
db: Database session
|
||||
email: User's email address
|
||||
|
||||
Returns:
|
||||
User if found, None otherwise
|
||||
"""
|
||||
result = await db.execute(
|
||||
select(User).where(User.email == email)
|
||||
)
|
||||
return result.scalar_one_or_none()
|
||||
```
|
||||
|
||||
### Frontend (TypeScript/React)
|
||||
|
||||
- **Style**: Use Prettier (configured)
|
||||
- **TypeScript**: Strict mode, no `any` types
|
||||
- **Components**: Functional components with hooks
|
||||
- **Naming**: PascalCase for components, camelCase for functions
|
||||
- **Imports**: Use absolute imports with `@/` alias
|
||||
- **Dependencies**: Use provided auth context (never import stores directly)
|
||||
|
||||
Example:
|
||||
```typescript
|
||||
interface UserProfileProps {
|
||||
userId: string;
|
||||
}
|
||||
|
||||
export function UserProfile({ userId }: UserProfileProps) {
|
||||
const { user } = useAuth();
|
||||
const { data, isLoading } = useQuery({
|
||||
queryKey: ['user', userId],
|
||||
queryFn: () => fetchUser(userId),
|
||||
});
|
||||
|
||||
if (isLoading) return <LoadingSpinner />;
|
||||
|
||||
return <div>...</div>;
|
||||
}
|
||||
```
|
||||
|
||||
### Key Patterns
|
||||
|
||||
- **Backend**: Use CRUD pattern, keep routes thin, business logic in services
|
||||
- **Frontend**: Use React Query for server state, Zustand for client state
|
||||
- **Both**: Handle errors gracefully, log appropriately, write tests
|
||||
|
||||
---
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
### Backend Tests
|
||||
|
||||
- **Coverage target**: >90% for new code
|
||||
- **Test types**: Unit, integration, and security tests
|
||||
- **Fixtures**: Use pytest fixtures from `conftest.py`
|
||||
- **Database**: Use `async_test_db` fixture for isolation
|
||||
- **Assertions**: Be specific about what you're testing
|
||||
|
||||
```python
|
||||
@pytest.mark.asyncio
|
||||
async def test_create_user(client, async_test_superuser, superuser_token):
|
||||
"""Test creating a new user."""
|
||||
response = await client.post(
|
||||
"/api/v1/admin/users",
|
||||
headers={"Authorization": f"Bearer {superuser_token}"},
|
||||
json={
|
||||
"email": "newuser@example.com",
|
||||
"password": "SecurePass123!",
|
||||
"first_name": "New",
|
||||
"last_name": "User"
|
||||
}
|
||||
)
|
||||
|
||||
assert response.status_code == 201
|
||||
data = response.json()
|
||||
assert data["email"] == "newuser@example.com"
|
||||
assert "password" not in data # Never expose passwords
|
||||
```
|
||||
|
||||
### Frontend E2E Tests
|
||||
|
||||
- **Use Playwright**: For end-to-end user flows
|
||||
- **Be specific**: Use accessible selectors (roles, labels)
|
||||
- **Be reliable**: Avoid flaky tests with proper waits
|
||||
- **Be fast**: Group related tests, use parallel execution
|
||||
|
||||
```typescript
|
||||
test('user can login and view profile', async ({ page }) => {
|
||||
// Login
|
||||
await page.goto('/auth/login');
|
||||
await page.fill('#email', 'user@example.com');
|
||||
await page.fill('#password', 'password123');
|
||||
await page.click('button[type="submit"]');
|
||||
|
||||
// Should redirect to dashboard
|
||||
await expect(page).toHaveURL(/\/dashboard/);
|
||||
|
||||
// Should see user name
|
||||
await expect(page.getByText('Welcome, John')).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
### Unit Tests (Frontend)
|
||||
|
||||
- **Test behavior**: Not implementation details
|
||||
- **Mock dependencies**: Use Jest mocks appropriately
|
||||
- **Test accessibility**: Include a11y checks when relevant
|
||||
|
||||
---
|
||||
|
||||
## Commit Messages
|
||||
|
||||
Write clear, descriptive commit messages:
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
<type>: <subject>
|
||||
|
||||
<body (optional)>
|
||||
|
||||
<footer (optional)>
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Code style changes (formatting, no logic change)
|
||||
- `refactor`: Code refactoring
|
||||
- `test`: Adding or updating tests
|
||||
- `chore`: Maintenance tasks
|
||||
|
||||
### Examples
|
||||
|
||||
**Good:**
|
||||
```
|
||||
feat: add password reset flow
|
||||
|
||||
Implements complete password reset with email tokens.
|
||||
Tokens expire after 1 hour for security.
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
**Also good (simple change):**
|
||||
```
|
||||
fix: correct pagination offset calculation
|
||||
```
|
||||
|
||||
**Not great:**
|
||||
```
|
||||
Fixed stuff
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
### Before Submitting
|
||||
|
||||
- [ ] Code follows project style guidelines
|
||||
- [ ] All tests pass locally
|
||||
- [ ] New tests added for new features
|
||||
- [ ] Documentation updated if needed
|
||||
- [ ] No merge conflicts with `main`
|
||||
- [ ] Commits are logical and well-described
|
||||
|
||||
### PR Template
|
||||
|
||||
```markdown
|
||||
## Description
|
||||
Brief description of changes
|
||||
|
||||
## Type of Change
|
||||
- [ ] Bug fix
|
||||
- [ ] New feature
|
||||
- [ ] Documentation update
|
||||
- [ ] Refactoring
|
||||
|
||||
## Testing
|
||||
How was this tested?
|
||||
|
||||
## Screenshots (if applicable)
|
||||
|
||||
## Checklist
|
||||
- [ ] Tests added/updated
|
||||
- [ ] Documentation updated
|
||||
- [ ] No breaking changes
|
||||
- [ ] Follows coding standards
|
||||
```
|
||||
|
||||
### Review Process
|
||||
|
||||
1. **Submit PR** with clear description
|
||||
2. **CI checks** must pass (when implemented)
|
||||
3. **Code review** by maintainers
|
||||
4. **Address feedback** if requested
|
||||
5. **Approval** from at least one maintainer
|
||||
6. **Merge** by maintainer
|
||||
|
||||
### After Merge
|
||||
|
||||
- Your contribution will be in the next release
|
||||
- You'll be added to contributors list
|
||||
- Feel awesome! 🎉
|
||||
|
||||
---
|
||||
|
||||
## Questions?
|
||||
|
||||
- **Documentation issues?** Ask in your PR or issue
|
||||
- **Unsure about implementation?** Open a discussion first
|
||||
- **Need help?** Tag maintainers in your issue/PR
|
||||
|
||||
---
|
||||
|
||||
## Recognition
|
||||
|
||||
Contributors are recognized in:
|
||||
- GitHub contributors page
|
||||
- Release notes (for significant contributions)
|
||||
- README acknowledgments (for major features)
|
||||
|
||||
---
|
||||
|
||||
Thank you for contributing! Every contribution, no matter how small, makes this template better for everyone. 🚀
|
||||
513
README.md
Normal file
513
README.md
Normal file
@@ -0,0 +1,513 @@
|
||||
# FastAPI + Next.js Full-Stack Template
|
||||
|
||||
> **Production-ready, security-first, full-stack TypeScript/Python template with authentication, multi-tenancy, and a comprehensive admin panel.**
|
||||
|
||||
[](./backend)
|
||||
[](./backend)
|
||||
[](./frontend/e2e)
|
||||
[](./LICENSE)
|
||||
[](./CONTRIBUTING.md)
|
||||
|
||||
---
|
||||
|
||||
## Why This Template?
|
||||
|
||||
Building a modern full-stack application from scratch means solving the same problems over and over: authentication, authorization, multi-tenancy, admin panels, session management, database migrations, API documentation, testing infrastructure...
|
||||
|
||||
**This template gives you all of that, battle-tested and ready to go.**
|
||||
|
||||
Instead of spending weeks on boilerplate, you can focus on building your unique features. Whether you're building a SaaS product, an internal tool, or a side project, this template provides a rock-solid foundation with modern best practices baked in.
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features
|
||||
|
||||
### 🔐 **Authentication & Security**
|
||||
- JWT-based authentication with access + refresh tokens
|
||||
- Session management with device tracking and revocation
|
||||
- Password reset flow (email integration ready)
|
||||
- Secure password hashing (bcrypt)
|
||||
- CSRF protection, rate limiting, and security headers
|
||||
- Comprehensive security tests (JWT algorithm attacks, session hijacking, privilege escalation)
|
||||
|
||||
### 👥 **Multi-Tenancy & Organizations**
|
||||
- Full organization system with role-based access control (Owner, Admin, Member)
|
||||
- Invite/remove members, manage permissions
|
||||
- Organization-scoped data access
|
||||
- User can belong to multiple organizations
|
||||
|
||||
### 🛠️ **Admin Panel**
|
||||
- Complete user management (CRUD, activate/deactivate, bulk operations)
|
||||
- Organization management (create, edit, delete, member management)
|
||||
- Session monitoring across all users
|
||||
- Real-time statistics dashboard
|
||||
- Admin-only routes with proper authorization
|
||||
|
||||
### 🎨 **Modern Frontend**
|
||||
- Next.js 15 with App Router and React 19
|
||||
- Comprehensive design system built on shadcn/ui + TailwindCSS
|
||||
- Pre-configured theme with dark mode support (coming soon)
|
||||
- Responsive, accessible components (WCAG AA compliant)
|
||||
- Developer documentation at `/dev` (in progress)
|
||||
|
||||
### 🧪 **Testing Infrastructure**
|
||||
- **Backend**: 743 tests, 97% coverage
|
||||
- Unit tests, integration tests, security tests
|
||||
- Async database testing with SQLAlchemy
|
||||
- API endpoint testing with test fixtures
|
||||
- **Frontend**: 56 E2E tests with Playwright
|
||||
- Zero flaky tests
|
||||
- Authentication flows, navigation, forms
|
||||
- Settings pages, session management
|
||||
|
||||
### 📚 **Developer Experience**
|
||||
- Auto-generated TypeScript API client from OpenAPI spec
|
||||
- Interactive API documentation (Swagger + ReDoc)
|
||||
- Database migrations with Alembic
|
||||
- Hot reload in development
|
||||
- Comprehensive code documentation
|
||||
- Docker support for easy deployment
|
||||
- VSCode workspace settings included
|
||||
|
||||
### 📊 **Ready for Production**
|
||||
- Docker + docker-compose setup
|
||||
- Environment-based configuration
|
||||
- Database connection pooling
|
||||
- Error handling and logging
|
||||
- Health check endpoints
|
||||
- Production security headers
|
||||
- Rate limiting on sensitive endpoints
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Tech Stack
|
||||
|
||||
### Backend
|
||||
- **[FastAPI](https://fastapi.tiangolo.com/)** - Modern async Python web framework
|
||||
- **[SQLAlchemy 2.0](https://www.sqlalchemy.org/)** - Powerful ORM with async support
|
||||
- **[PostgreSQL](https://www.postgresql.org/)** - Robust relational database
|
||||
- **[Alembic](https://alembic.sqlalchemy.org/)** - Database migrations
|
||||
- **[Pydantic v2](https://docs.pydantic.dev/)** - Data validation with type hints
|
||||
- **[pytest](https://pytest.org/)** - Testing framework with async support
|
||||
|
||||
### Frontend
|
||||
- **[Next.js 15](https://nextjs.org/)** - React framework with App Router
|
||||
- **[React 19](https://react.dev/)** - UI library
|
||||
- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript
|
||||
- **[TailwindCSS](https://tailwindcss.com/)** - Utility-first CSS framework
|
||||
- **[shadcn/ui](https://ui.shadcn.com/)** - Beautiful, accessible component library
|
||||
- **[TanStack Query](https://tanstack.com/query)** - Powerful data fetching/caching
|
||||
- **[Zustand](https://zustand-demo.pmnd.rs/)** - Lightweight state management
|
||||
- **[Playwright](https://playwright.dev/)** - End-to-end testing
|
||||
|
||||
### DevOps
|
||||
- **[Docker](https://www.docker.com/)** - Containerization
|
||||
- **[docker-compose](https://docs.docker.com/compose/)** - Multi-container orchestration
|
||||
- **GitHub Actions** (coming soon) - CI/CD pipelines
|
||||
|
||||
---
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
- **Docker & Docker Compose** (recommended) - [Install Docker](https://docs.docker.com/get-docker/)
|
||||
- **OR manually:**
|
||||
- Python 3.12+
|
||||
- Node.js 18+ (Node 20+ recommended)
|
||||
- PostgreSQL 15+
|
||||
|
||||
---
|
||||
|
||||
## 🏃 Quick Start (Docker)
|
||||
|
||||
The fastest way to get started is with Docker:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/fast-next-template.git
|
||||
cd fast-next-template
|
||||
|
||||
# Copy environment files
|
||||
cp backend/.env.example backend/.env
|
||||
cp frontend/.env.local.example frontend/.env.local
|
||||
|
||||
# Start all services (backend, frontend, database)
|
||||
docker-compose up
|
||||
|
||||
# In another terminal, run database migrations
|
||||
docker-compose exec backend alembic upgrade head
|
||||
|
||||
# Create first superuser (optional)
|
||||
docker-compose exec backend python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())"
|
||||
```
|
||||
|
||||
**That's it! 🎉**
|
||||
|
||||
- Frontend: http://localhost:3000
|
||||
- Backend API: http://localhost:8000
|
||||
- API Docs: http://localhost:8000/docs
|
||||
|
||||
Default superuser credentials:
|
||||
- Email: `admin@example.com`
|
||||
- Password: `admin123`
|
||||
|
||||
**⚠️ Change these immediately in production!**
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Manual Setup (Development)
|
||||
|
||||
### Backend Setup
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Setup environment
|
||||
cp .env.example .env
|
||||
# Edit .env with your database credentials
|
||||
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Initialize database with first superuser
|
||||
python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())"
|
||||
|
||||
# Start development server
|
||||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
### Frontend Setup
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Setup environment
|
||||
cp .env.local.example .env.local
|
||||
# Edit .env.local with your backend URL
|
||||
|
||||
# Generate API client
|
||||
npm run generate:api
|
||||
|
||||
# Start development server
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Visit http://localhost:3000 to see your app!
|
||||
|
||||
---
|
||||
|
||||
## 📂 Project Structure
|
||||
|
||||
```
|
||||
├── backend/ # FastAPI backend
|
||||
│ ├── app/
|
||||
│ │ ├── api/ # API routes and dependencies
|
||||
│ │ ├── core/ # Core functionality (auth, config, database)
|
||||
│ │ ├── crud/ # Database operations
|
||||
│ │ ├── models/ # SQLAlchemy models
|
||||
│ │ ├── schemas/ # Pydantic schemas
|
||||
│ │ ├── services/ # Business logic
|
||||
│ │ └── utils/ # Utilities
|
||||
│ ├── tests/ # Backend tests (97% coverage)
|
||||
│ ├── alembic/ # Database migrations
|
||||
│ └── docs/ # Backend documentation
|
||||
│
|
||||
├── frontend/ # Next.js frontend
|
||||
│ ├── src/
|
||||
│ │ ├── app/ # Next.js App Router pages
|
||||
│ │ ├── components/ # React components
|
||||
│ │ ├── lib/ # Libraries and utilities
|
||||
│ │ │ ├── api/ # API client (auto-generated)
|
||||
│ │ │ └── stores/ # Zustand stores
|
||||
│ │ └── hooks/ # Custom React hooks
|
||||
│ ├── e2e/ # Playwright E2E tests
|
||||
│ ├── tests/ # Unit tests (Jest)
|
||||
│ └── docs/ # Frontend documentation
|
||||
│ └── design-system/ # Comprehensive design system docs
|
||||
│
|
||||
├── docker-compose.yml # Docker orchestration
|
||||
├── docker-compose.dev.yml # Development with hot reload
|
||||
└── README.md # You are here!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
This template takes testing seriously. Here's what you get:
|
||||
|
||||
### Backend Tests (743 tests, 97% coverage)
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Run all tests
|
||||
IS_TEST=True pytest
|
||||
|
||||
# Run with coverage report
|
||||
IS_TEST=True pytest --cov=app --cov-report=term-missing
|
||||
|
||||
# Run specific test file
|
||||
IS_TEST=True pytest tests/api/test_auth.py -v
|
||||
|
||||
# Generate HTML coverage report
|
||||
IS_TEST=True pytest --cov=app --cov-report=html
|
||||
open htmlcov/index.html
|
||||
```
|
||||
|
||||
**Coverage breakdown:**
|
||||
- User CRUD: 100%
|
||||
- Session CRUD: 100%
|
||||
- Organization routes: 100%
|
||||
- Auth routes: 99%
|
||||
- Permissions: 100%
|
||||
|
||||
### Frontend E2E Tests (56 passing, 0 flaky)
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Run E2E tests
|
||||
npm run test:e2e
|
||||
|
||||
# Run E2E tests in UI mode (recommended for development)
|
||||
npm run test:e2e:ui
|
||||
|
||||
# Run specific test file
|
||||
npx playwright test auth-login.spec.ts
|
||||
|
||||
# Generate test report
|
||||
npx playwright show-report
|
||||
```
|
||||
|
||||
**Test coverage:**
|
||||
- Authentication flows (login, register, password reset)
|
||||
- Navigation and routing
|
||||
- Settings pages (profile, password, sessions)
|
||||
- Admin panel (in progress)
|
||||
|
||||
### Frontend Unit Tests
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
|
||||
# Run unit tests
|
||||
npm test
|
||||
|
||||
# Run with coverage
|
||||
npm run test:coverage
|
||||
|
||||
# Watch mode
|
||||
npm run test:watch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ Database Migrations
|
||||
|
||||
The template uses Alembic for database migrations:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Generate migration from model changes
|
||||
python migrate.py generate "description of changes"
|
||||
|
||||
# Apply migrations
|
||||
python migrate.py apply
|
||||
|
||||
# Or do both in one command
|
||||
python migrate.py auto "description"
|
||||
|
||||
# View migration history
|
||||
python migrate.py list
|
||||
|
||||
# Check current revision
|
||||
python migrate.py current
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Documentation
|
||||
|
||||
### Backend Documentation
|
||||
|
||||
- **[ARCHITECTURE.md](./backend/docs/ARCHITECTURE.md)** - System architecture and design patterns
|
||||
- **[CODING_STANDARDS.md](./backend/docs/CODING_STANDARDS.md)** - Code quality standards
|
||||
- **[COMMON_PITFALLS.md](./backend/docs/COMMON_PITFALLS.md)** - Common mistakes to avoid
|
||||
- **[FEATURE_EXAMPLE.md](./backend/docs/FEATURE_EXAMPLE.md)** - Step-by-step feature guide
|
||||
- **[CLAUDE.md](./CLAUDE.md)** - Comprehensive development guide
|
||||
|
||||
### Frontend Documentation
|
||||
|
||||
- **[Design System Docs](./frontend/docs/design-system/)** - Complete design system guide
|
||||
- Quick start, foundations (colors, typography, spacing)
|
||||
- Component library guide
|
||||
- Layout patterns, spacing philosophy
|
||||
- Forms, accessibility, AI guidelines
|
||||
- **[ARCHITECTURE_FIX_REPORT.md](./frontend/docs/ARCHITECTURE_FIX_REPORT.md)** - Critical dependency injection patterns
|
||||
- **[E2E Testing Guide](./frontend/e2e/README.md)** - E2E testing setup and best practices
|
||||
|
||||
### API Documentation
|
||||
|
||||
When the backend is running:
|
||||
- **Swagger UI**: http://localhost:8000/docs
|
||||
- **ReDoc**: http://localhost:8000/redoc
|
||||
- **OpenAPI JSON**: http://localhost:8000/api/v1/openapi.json
|
||||
|
||||
---
|
||||
|
||||
## 🚢 Deployment
|
||||
|
||||
### Docker Production Deployment
|
||||
|
||||
```bash
|
||||
# Build and start all services
|
||||
docker-compose up -d
|
||||
|
||||
# Run migrations
|
||||
docker-compose exec backend alembic upgrade head
|
||||
|
||||
# View logs
|
||||
docker-compose logs -f
|
||||
|
||||
# Stop services
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### Production Checklist
|
||||
|
||||
- [ ] Change default superuser credentials
|
||||
- [ ] Set strong `SECRET_KEY` in backend `.env`
|
||||
- [ ] Configure production database (PostgreSQL)
|
||||
- [ ] Set `ENVIRONMENT=production` in backend
|
||||
- [ ] Configure CORS origins for your domain
|
||||
- [ ] Setup SSL/TLS certificates
|
||||
- [ ] Configure email service for password resets
|
||||
- [ ] Setup monitoring and logging
|
||||
- [ ] Configure backup strategy
|
||||
- [ ] Review and adjust rate limits
|
||||
- [ ] Test security headers
|
||||
|
||||
---
|
||||
|
||||
## 🛣️ Roadmap & Status
|
||||
|
||||
### ✅ Completed
|
||||
- [x] Authentication system (JWT, refresh tokens, session management)
|
||||
- [x] User management (CRUD, profile, password change)
|
||||
- [x] Organization system with RBAC (Owner, Admin, Member)
|
||||
- [x] Admin panel (users, organizations, sessions, statistics)
|
||||
- [x] Backend testing infrastructure (97% coverage)
|
||||
- [x] Frontend E2E testing (Playwright)
|
||||
- [x] Design system documentation
|
||||
- [x] Database migrations
|
||||
- [x] Docker deployment
|
||||
- [x] API documentation (OpenAPI/Swagger)
|
||||
|
||||
### 🚧 In Progress
|
||||
- [ ] Frontend admin pages (70% complete)
|
||||
- [ ] Dark mode theme
|
||||
- [ ] `/dev` documentation page with examples
|
||||
- [ ] Email integration (templates ready, SMTP pending)
|
||||
- [ ] Chart/visualization components
|
||||
|
||||
### 🔮 Planned
|
||||
- [ ] GitHub Actions CI/CD pipelines
|
||||
- [ ] Test coverage badges
|
||||
- [ ] Additional authentication methods (OAuth, SSO)
|
||||
- [ ] Webhook system
|
||||
- [ ] Background job processing
|
||||
- [ ] File upload/storage
|
||||
- [ ] Notification system
|
||||
- [ ] Audit logging
|
||||
- [ ] API versioning example
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Whether you're fixing bugs, improving documentation, or proposing new features, we'd love your help.
|
||||
|
||||
### How to Contribute
|
||||
|
||||
1. **Fork the repository**
|
||||
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
|
||||
3. **Make your changes**
|
||||
- Follow existing code style
|
||||
- Add tests for new features
|
||||
- Update documentation as needed
|
||||
4. **Run tests** to ensure everything works
|
||||
5. **Commit your changes** (`git commit -m 'Add amazing feature'`)
|
||||
6. **Push to your branch** (`git push origin feature/amazing-feature`)
|
||||
7. **Open a Pull Request**
|
||||
|
||||
### Development Guidelines
|
||||
|
||||
- Write tests for new features (aim for >90% coverage)
|
||||
- Follow the existing architecture patterns
|
||||
- Update documentation when adding features
|
||||
- Keep commits atomic and well-described
|
||||
- Be respectful and constructive in discussions
|
||||
|
||||
### Reporting Issues
|
||||
|
||||
Found a bug? Have a suggestion? [Open an issue](https://github.com/yourusername/fast-next-template/issues)!
|
||||
|
||||
Please include:
|
||||
- Clear description of the issue/suggestion
|
||||
- Steps to reproduce (for bugs)
|
||||
- Expected vs. actual behavior
|
||||
- Environment details (OS, Python/Node version, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the **MIT License** - see the [LICENSE](./LICENSE) file for details.
|
||||
|
||||
**TL;DR**: You can use this template for any purpose, commercial or non-commercial. Attribution is appreciated but not required!
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
This template is built on the shoulders of giants:
|
||||
|
||||
- [FastAPI](https://fastapi.tiangolo.com/) by Sebastián Ramírez
|
||||
- [Next.js](https://nextjs.org/) by Vercel
|
||||
- [shadcn/ui](https://ui.shadcn.com/) by shadcn
|
||||
- [TanStack Query](https://tanstack.com/query) by Tanner Linsley
|
||||
- [Playwright](https://playwright.dev/) by Microsoft
|
||||
- And countless other open-source projects that make modern development possible
|
||||
|
||||
---
|
||||
|
||||
## 💬 Questions?
|
||||
|
||||
- **Documentation**: Check the `/docs` folders in backend and frontend
|
||||
- **Issues**: [GitHub Issues](https://github.com/yourusername/fast-next-template/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/fast-next-template/discussions)
|
||||
|
||||
---
|
||||
|
||||
## ⭐ Star This Repo
|
||||
|
||||
If this template saves you time, consider giving it a star! It helps others discover the project and motivates continued development.
|
||||
|
||||
**Happy coding! 🚀**
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
Made with ❤️ by a developer who got tired of rebuilding the same boilerplate
|
||||
</div>
|
||||
Reference in New Issue
Block a user