Backend Task: Build FastAPI Notes Application

[tajirdev]

📌 Task Overview

Build a complete FastAPI backend for a Notes Application.

The purpose of this task is not only to make the application work, but also to demonstrate that the backend follows our Backend Engineering Standards.

Before starting development, read the Backend Engineering Standards Developer Quick Guide and refer to the full standards repository whenever you need detailed implementation guidance.

Full Backend Engineering Standards:
https://github.com/tajirdev/backend-engineering-standards

---

🎯 Main Objective

Create a production-quality FastAPI backend that allows authenticated users to create and manage their own notes while administrators can manage the entire platform.

The backend must include:

• Notes CRUD
• PostgreSQL database
• Authentication
• Role-Based Access Control (RBAC)
• Admin and User roles
• File upload/storage
• Validation
• Error handling
• Testing
• API documentation
• Proper Git workflow

---

1. Notes Management

Implement complete CRUD functionality for notes.

Create Note

Authenticated users must be able to create a note.

A note should contain appropriate fields such as:

• ID
• Title
• Content
• Owner/user ID
• Created timestamp
• Updated timestamp

Additional fields may be added where they provide a clear purpose.

Read Notes

Users must be able to:

• Get their own notes
• Get a single note
• List their notes

Users must not be able to access another user's private notes.

Update Note

Users must be able to edit their own notes.

A user must not be able to edit another user's note.

Delete Note

Users must be able to delete their own notes.

A user must not be able to delete another user's note.

---

2. PostgreSQL Database

Use PostgreSQL as the primary database.

Use:

• SQLAlchemy 2.x
• Alembic

Requirements:

• Proper primary keys
• Foreign keys
• Relationships
• Appropriate constraints
• Appropriate indexes
• Created/updated timestamps where necessary

All database schema changes must be handled through Alembic migrations.

Do not manually modify the database schema without a migration.

---

3. Authentication

Implement a complete authentication system.

Users must be authenticated before they can:

• Create notes
• Read protected notes
• Update notes
• Delete notes
• Upload files

The authentication system should include appropriate functionality such as:

• User registration
• Login
• Password hashing
• Access-token authentication
• Token expiration
• Current-user dependency

Passwords must never be stored as plaintext.

Use Argon2id for password hashing for the new application.

---

4. Role-Based Access Control (RBAC)

Implement RBAC with at least two roles:

admin
user

Admin

An administrator has full platform control.

Admin must be able to:

• View users
• View any note
• Create/edit/delete notes where appropriate
• Delete any user's note
• Manage users
• Perform administrative operations

Admin-only endpoints must be protected by backend authorization.

User

A normal user can:

• Manage their own account where applicable
• Create notes
• View their own notes
• Edit their own notes
• Delete their own notes
• Upload files associated with their notes

A user must not:

• Access another user's private notes
• Modify another user's notes
• Delete another user's notes
• Access admin-only endpoints
• Manage other users

Important

Authentication and authorization are different.

The backend must verify both:

Who is the user?
        ↓
What is the user allowed to do?
        ↓
Does the user own this resource?

Do not rely on frontend restrictions for authorization.

---

5. Centralized File Storage

Implement centralized storage for files uploaded by users.

The application must support at least:

• Images
• PDF files

Requirements:

• Validate file type
• Validate file size
• Generate safe filenames
• Prevent path traversal
• Do not trust the original filename
• Associate uploaded files with the correct user/note
• Protect private files from unauthorized access

For local development, a structured local storage system may be used.

The storage design should make it possible to replace local storage with object storage such as S3-compatible storage later without rewriting the entire application.

---

6. API Design

Follow REST API conventions.

Use:

• Appropriate HTTP methods
• Appropriate HTTP status codes
• Request schemas
• Response schemas
• Validation
• Pagination where necessary
• Filtering/searching where appropriate

Do not return database models directly when a response schema should be used.

Examples:

POST   /api/v1/notes
GET    /api/v1/notes
GET    /api/v1/notes/{note_id}
PATCH  /api/v1/notes/{note_id}
DELETE /api/v1/notes/{note_id}

The exact endpoint structure may be adjusted if there is a strong engineering reason.

---

7. Validation

Validate all client input.

Examples:

• Required title
• Title length
• Content length where appropriate
• Valid IDs
• Valid file types
• Maximum file size
• Valid authentication data

Do not depend only on frontend validation.

Backend validation is mandatory.

---

8. Error Handling

Implement consistent error handling.

The API should correctly handle:

• Invalid input
• Invalid credentials
• Missing resources
• Unauthorized access
• Forbidden actions
• Duplicate records
• Database errors
• Invalid file uploads
• Unexpected server errors

Do not expose:

• Stack traces
• Database errors
• Passwords
• Tokens
• Secrets
• Internal implementation details

Avoid careless usage of:

except Exception:

---

9. Testing

Use Pytest.

Tests should cover important functionality.

At minimum test:

Authentication

• Registration
• Login
• Invalid login
• Protected endpoint without authentication
• Invalid/expired token

Authorization

• Admin accessing admin endpoint
• User accessing normal endpoint
• User attempting admin endpoint
• User accessing own note
• User attempting to access another user's note
• User attempting to edit another user's note
• User attempting to delete another user's note

Notes

• Create note
• Get notes
• Get single note
• Update note
• Delete note
• Missing note
• Invalid input

File Uploads

• Valid image
• Valid PDF
• Invalid file type
• Oversized file
• Unauthorized file access

---

10. API Documentation

FastAPI's OpenAPI documentation must be properly maintained.

The API should have:

• Meaningful endpoint summaries
• Request schemas
• Response schemas
• Authentication requirements
• Useful error responses

Swagger/OpenAPI should accurately represent the actual API behavior.

---

11. Configuration & Environment Variables

Do not hardcode:

• Database credentials
• JWT secrets
• API keys
• Storage credentials
• Other sensitive configuration

Use environment variables.

Provide:

.env.example

but never commit the actual:

.env

file containing secrets.

---

12. Logging

Implement useful backend logging.

Log appropriate:

• Application errors
• Important operations
• Authentication/security events where appropriate

Never log:

• Passwords
• Access tokens
• Refresh tokens
• API keys
• Database passwords
• Sensitive user information unnecessarily

---

13. Project Structure

Follow a clean and understandable project structure.

For example:

app/
├── main.py
├── core/
├── api/
├── models/
├── schemas/
├── services/
├── repositories/
├── dependencies/
├── storage/
└── tests/

The exact structure may differ, but responsibilities must remain clearly separated.

Do not put all application logic inside one file.

Routes should not contain large amounts of business logic.

---

14. Git Workflow

Step 1 — Start from dev

Make sure the local repository is up to date.

Create the feature branch from:

dev

Step 2 — Create a branch using your name

Use the following naming format:

<name>_note

Example:

Alfred_note

Use the developer's own name.

Do not develop directly on:

main
dev

---

15. Commits

Make meaningful commits.

Avoid commits such as:

update
fix
changes
test
final
final-final

Prefer commits such as:

feat: add user authentication
feat: implement notes CRUD
feat: add note ownership authorization
feat: add centralized file storage
test: add notes API tests
fix: prevent unauthorized note access

Keep commits focused on related changes.

---

16. Pull Request

When the task is complete:

1. Push the branch to GitHub.
2. Open a Pull Request.
3. The Pull Request should target:

dev

4. Add the backend lead as a reviewer.
5. Do not merge the Pull Request yourself.
6. Resolve all review comments.
7. Make sure CI/tests pass before requesting final approval.

Reviewer

Add:

@tajirdev

as the reviewer.

---

17. Definition of Done

The task is considered complete only when:

• FastAPI application runs successfully
• PostgreSQL database is configured
• Alembic migrations are implemented
• User registration works
• Login works
• Passwords are securely hashed
• Authentication is implemented
• RBAC is implemented
• Admin role works
• User role works
• Notes CRUD works
• Note ownership is enforced
• Admin can manage platform resources
• File uploads work
• Images are supported
• PDFs are supported
• File validation exists
• Error handling is implemented
• Input validation exists
• Appropriate HTTP status codes are used
• Pagination is implemented where required
• Logging is implemented appropriately
• Environment variables are used
• .env is not committed
• API documentation is accurate
• Tests are implemented
• Tests pass
• Code follows the Backend Engineering Standards
• Git branch follows the required naming convention
• Pull Request is created against dev
• @tajirdev is added as reviewer

---

⚠️ Important

Do not start coding before reading the Backend Engineering Standards Developer Quick Guide.

The quick guide gives the required standards at a glance.

For detailed explanations and implementation examples, refer to:

Backend Engineering Standards

https://github.com/tajirdev/backend-engineering-standards

The repository contains:

• Architecture standards
• API guidelines
• Database guidelines
• Authentication standards
• Error handling
• Security standards
• Testing standards
• Git workflow
• Code review standards
• ❌ Bad examples
• ✅ Good examples
• Backend audit checklist

---

📅 Deadline

Deadline: Friday

The Pull Request must be created before the deadline.

Do not wait until the last few hours to push the entire project.

Push regularly and keep the branch updated.

---

Final Reminder

The goal of this task is not just:

"Make a Notes API."

The goal is:

Build a backend that another developer can safely understand, maintain, test and extend.

Follow the standards from the beginning rather than trying to clean up the code at the end.

Good luck and have a productive week! 🚀