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