feat: RBAC for Fullstack Dev Test Task

.env

@@ -3,10 +3,15 @@ FASTAPI_ENV=development
 
 PROJECT_NAME="Full Stack FastAPI Project"
 
-SECRET_KEY=changethis
+SECRET_KEY=dev-local-jwt-secret-key-minimum-32-characters-long
 FIRST_SUPERUSER=admin@example.com
 FIRST_SUPERUSER_PASSWORD=changethis
 
+MANAGER_USER=manager@example.com
+MANAGER_USER_PASSWORD=changethis
+MEMBER_USER=member@example.com
+MEMBER_USER_PASSWORD=changethis
+
 # Emails
 SMTP_HOST=localhost
 EMAILS_FROM_EMAIL=info@example.com

.github/workflows/playwright.yml

@@ -45,6 +45,8 @@ jobs:
     if: ${{ needs.changes.outputs.changed == 'true' }}
     timeout-minutes: 15
     runs-on: ubuntu-latest
+    env:
+      COMPOSE_FILE: compose.yml:compose.override.example.yml
     strategy:
       matrix:
         shardIndex: [1, 2, 3, 4]

.github/workflows/test-backend.yml

@@ -12,6 +12,8 @@ jobs:
   test-backend:
     runs-on: ubuntu-latest
     timeout-minutes: 5
+    env:
+      COMPOSE_FILE: compose.yml:compose.override.example.yml
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/test-docker-compose.yml

@@ -13,6 +13,8 @@ jobs:
   test-docker-compose:
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    env:
+      COMPOSE_FILE: compose.yml:compose.override.example.yml
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.gitignore

@@ -1,8 +1,12 @@
 .vscode/*
 !.vscode/extensions.json
+.idea/
+.agents/
+.claude/
 node_modules/
 backend/app/frontend/
 /test-results/
 /playwright-report/
 /blob-report/
 /playwright/.cache/
+compose.override.yml

NOTES.md

@@ -0,0 +1,41 @@
+# Notes for Reviewers
+
+Supplementary context for the [Fullstack Dev Test Task](https://github.com/evios/Fullstack-Dev-Test-Task). Required deliverables are in `README.md`; this file covers scope, trade-offs, and follow-ups.
+
+## What Was Prioritized
+
+1. **Centralized backend policy** — `permissions.py` + `require_permission()` dependencies.
+2. **Consistent frontend UX** — hidden nav, route guards, `AccessDenied` component.
+3. **Focused tests** — eight authorization scenarios (allow + deny paths), including denial logging.
+4. **Runnable setup** — Docker Compose, seed users, migration, smoke script.
+
+## Scope Cuts (and Why)
+
+| Cut | Reason |
+|-----|--------|
+| E2E Playwright tests for RBAC | Backend tests + manual smoke cover critical paths within timebox |
+| `/me/permissions` API | Small static matrix; mirroring in frontend is simpler (see ADR 002) |
+| Row-level / resource ownership rules | Assignment surface is role-based, not object-level ACL |
+| Regenerating OpenAPI client for `role` | Patched `types.gen.ts` manually; `generate-client.sh` needs running stack |
+
+## Trade-offs
+
+- **`is_superuser` is derived from `role`** — PostgreSQL generated column plus read-only `@computed_field` in API responses; writable schemas accept `role` only (`extra="forbid"` blocks legacy `is_superuser` input).
+- **Items use the permission layer** — Admin holds `items:list_any` / `items:manage_any`; manager and member manage only their own items.
+- **Frontend permission duplication** — Acceptable for three roles; would generate or fetch capabilities in a larger system.
+
+## Observability
+
+Denied authorization attempts are logged at `WARNING` from `app.api.deps` with user id, email, role, and requested permission or required roles. Useful for audit trails and debugging mistaken 403 responses.
+
+## With More Time
+
+- Add Playwright flows: login as member → direct `/admin` → see Access Denied.
+- Expose read-only permissions in OpenAPI and regenerate the frontend client.
+- Structured audit log table for denied access (not only application logs).
+- Feature flags or admin UI to assign roles without DB access.
+
+## Architecture Docs
+
+- ADRs: `docs/adr/001-permission-based-rbac.md`, `docs/adr/002-frontend-permission-mirror.md`
+- Auth flow diagram: `README.md` (Mermaid)

README.md

@@ -1,3 +1,125 @@
+# Full Stack FastAPI Template — RBAC Extension
+
+This project extends the [Full Stack FastAPI Template](https://github.com/fastapi/full-stack-fastapi-template) with role-based access control (RBAC) for the [Fullstack Dev Test Task](https://github.com/evios/Fullstack-Dev-Test-Task).
+
+## Submission
+
+Fork PR: https://github.com/fastapi/full-stack-fastapi-template/pull/2445
+Fork: https://github.com/yanhub/full-stack-fastapi-template
+
+## Quick Start (Docker)
+
+Requires [Docker Desktop](https://www.docker.com/products/docker-desktop/) (macOS, Linux, or Windows).
+
+```bash
+git clone <repository-url>
+cd <project-directory>
+cp compose.override.example.yml compose.override.yml
+docker compose build backend
+docker compose run --rm backend bash scripts/prestart.sh
+docker compose up -d
+```
+
+Open:
+
+| Service | URL |
+|---------|-----|
+| App (API + frontend) | http://localhost:8000 |
+| API docs | http://localhost:8000/docs |
+| Adminer | http://localhost:8080 |
+| Mailpit | http://localhost:8025 |
+| Traefik (via proxy) | http://localhost |
+
+`compose.override.yml` is local-only (see `compose.override.example.yml`). Adjust ports there if `80` or `5432` are already in use on your machine.
+
+## Seed Users
+
+| Email | Password | Role |
+|-------|----------|------|
+| admin@example.com | changethis | admin |
+| manager@example.com | changethis | manager |
+| member@example.com | changethis | member |
+
+Credentials are configured in `.env` (`FIRST_SUPERUSER*`, `MANAGER_USER*`, `MEMBER_USER*`).
+
+## Permission Matrix
+
+| Action | admin | manager | member |
+|--------|:-----:|:-------:|:------:|
+| List all users | yes | yes | no |
+| Create user | yes | no | no |
+| View metrics | yes | yes | no |
+| Update own profile | yes | yes | yes |
+| Update any profile | yes | no | no |
+| Global settings | yes | no | no |
+| List all items | yes | no | no |
+| Manage any item (read/update/delete) | yes | no | no |
+| Manage own items | yes | yes | yes |
+
+## Authorization Approach
+
+Roles are stored on the `User.role` column (`admin`, `manager`, `member`) with an Alembic migration backfilling existing superusers to `admin`.
+
+Backend authorization is centralized in `backend/app/core/permissions.py`. FastAPI dependencies in `backend/app/api/deps.py` expose `require_permission(...)` and enforce checks on route handlers (users, metrics). The API returns HTTP `403` with a clear message when access is denied.
+
+The frontend mirrors the same permission matrix in `frontend/src/lib/permissions.ts`. The `usePermissions()` hook drives sidebar visibility, route-level UI guards, and an `AccessDenied` component for direct navigation to forbidden pages. The backend remains the source of truth; the UI only hides or blocks navigation for better UX.
+
+Denied access attempts are logged at `WARNING` level from `app.api.deps` (user id, email, role, permission) for observability.
+
+### Authorization Flow
+
+```mermaid
+flowchart TB
+  subgraph client [Frontend]
+    Login[Login / JWT stored]
+    Hook[usePermissions from user.role]
+    Nav[Sidebar hides forbidden links]
+    Guard[Route guard / AccessDenied]
+    Login --> Hook --> Nav
+    Hook --> Guard
+  end
+
+  subgraph api [Backend API]
+    JWT[get_current_user validates JWT]
+    Perm[require_permission dependency]
+    Matrix[user_has_permission in permissions.py]
+    Route[Route handler]
+    JWT --> Perm --> Matrix
+    Matrix -->|allowed| Route
+    Matrix -->|denied| Log403[Log WARNING + HTTP 403]
+  end
+
+  Guard -->|API call| JWT
+  Nav -->|API call| JWT
+```
+
+Further reading:
+
+- [NOTES.md](NOTES.md) — scope cuts, trade-offs, follow-ups
+- [docs/ai-conversations/](docs/ai-conversations/) — English copies of AI-assisted development sessions (submission requirement)
+- [docs/adr/001-permission-based-rbac.md](docs/adr/001-permission-based-rbac.md)
+- [docs/adr/002-frontend-permission-mirror.md](docs/adr/002-frontend-permission-mirror.md)
+
+## Running Tests
+
+```bash
+# Authorization-focused tests (rebuild backend image after pulling changes)
+docker compose run --rm backend pytest tests/api/routes/test_authorization.py -v
+
+# Smoke check (Python 3 on the host; stack must be up)
+python3 scripts/smoke_rbac.py
+```
+
+## Database Migrations
+
+```bash
+docker compose run --rm backend alembic upgrade head
+```
+
+New migration: `a1b2c3d4e5f6_add_user_role.py` (adds `role` column).
+
+---
+
 # Full Stack FastAPI Template
 
 [![Test Docker Compose](../../actions/workflows/test-docker-compose.yml/badge.svg)](../../actions/workflows/test-docker-compose.yml)