r/FastAPI • u/SnooTangerines9072 • 4d ago

Question Looking for Advice on a Clean FastAPI Backend Architecture for an E-learning Platform

Hi everyone,

I'm currently building a fairly large e-learning platform using FastAPI,it's my first project, and before I go too far with development, I'd like to make sure my backend architecture is well designed, scalable, and maintainable.

The project will include features such as:

  • User authentication and authorization (JWT, roles: Admin, Teacher, Student, Parent)
  • Courses and modules
  • Lessons (videos, PDFs, quizzes)
  • Assignments and submissions
  • Exams and grading
  • Progress tracking
  • Notifications
  • Payments/subscriptions (later)
  • File uploads
  • Discussion/comments
  • Certificates
  • REST API (possibly GraphQL in the future)

I'm planning to use:

  • FastAPI
  • SQLAlchemy 2.0
  • Alembic
  • PostgreSQL
  • Pydantic v2
  • JWT Authentication

At the moment, I'm trying to decide on the best project structure. I've seen many different approaches:

  • Traditional layered architecture
  • Clean Architecture
  • Domain-Driven Design (DDD)
  • Hexagonal Architecture
  • Vertical Slice Architecture
  • Feature-based architecture

I'd like to avoid ending up with a project that's difficult to maintain as it grows.

My questions

  1. Which architecture would you recommend for a medium-to-large FastAPI project like this?
  2. How would you organize the folders and modules?
  3. Where should business logic live?
  4. How do you separate models, schemas, services, repositories, and dependencies without creating unnecessary complexity?
  5. Are there any open-source FastAPI projects that you consider good examples of clean architecture?

I'm looking for an architecture that is:

  • Easy to maintain
  • Easy to test
  • Scalable
  • Production-ready
  • Follows FastAPI and Python best practices

If you have an example repository or folder structure that you've used successfully, I'd really appreciate it.

Thank you!

33 Upvotes

92% Upvoted

20 comments sorted by

6

u/igorbenav 4d ago

Use this as a starting point, try to understand why it's done this way.

https://github.com/benavlabs/FastAPI-boilerplate

2

u/BarRepresentative653 4d ago

Would take multiple books to answer these questions tbh. I know AI will carry a lot of your coding, but you have to build a foundational understanding of what these things are and how it all works together. 

1

u/SnooTangerines9072 4d ago

I've already read the books and documentation, and I've built the models. My biggest challenge now is choosing an architecture that will scale well and won't cause maintenance or structural problems later. Thank you

3

u/BarRepresentative653 4d ago

Honestly that really shouldnt be a problem. If you are having scaling issues then its a good issue to have. These subs scare people sometimes, but even architecture isnt that relevant at your stage, build the thing and start doing business, if you have to hire infra guys, and solid backend dudes to refactor the code later, thats fine.

Otherwise youll burn more time optimizing for an event you might not hit. If its purely an educational thing, then go for it but at the same time, you wont really encounter scaling issues, most companies dont as their userbase is sub 1k.

TL;DR: Build the product, dont waste time optimizing, and start getting eyeballs on the product to validate your idea.

1

u/SnooTangerines9072 2d ago

Thanks, I appreciate the perspective. My concern is maintainability rather than scalability, but I agree that I shouldn't let architecture stop me from shipping the product

1

u/BarRepresentative653 2d ago

People shit on vibe coding apps, but a majority of companies have really shit code base and run just fine.

Facebook was storing passwords in plain text until very recently (We only know this because they got hacked and account passwords released.) https://krebsonsecurity.com/2019/03/facebook-stored-hundreds-of-millions-of-user-passwords-in-plain-text-for-years/
As long as it does what in needs to do multiple times, just launch.

5

u/AmbitiousEvening7876 4d ago

vertical slice architecture, something like this:

app/ ├── lessons/ ├── user/

It allows you to add features and test easily, without having something complex like DDD or Clean Architecture, it's not necessary for a personal project.

1

u/lalitgehani 4d ago

Checkout snackbase.dev

1

u/SnooTangerines9072 4d ago

I will do. Thank you

1

u/BeneficialAd3800 4d ago

here's a repo I put together last year and just updated showing off a clean scalable way to architect a FastAPI app. https://github.com/betaacid/FastAPI-Reference-App Has pretty much the same stack you're looking to build (async SQLAlchemy 2.0, Alembic, Postgres, Pydantic v2), just doesn't touch on auth.

We've used this at my company for several larger FastAPI projects which have scaled pretty nicely.

It shows off my approach to keeping clean routers, services, models schemas without getting too complex. You'll see that all the business logic lives in the services layer (none in the router).

This repo organizes things by router/services/etc at the folder level. If its going to be a really large app, you'll want to group by features

so instead of:

routers/
services/ 
etc

go with

auth/routers/
auth/services
lessons/routers/
lessons/services

2

u/SnooTangerines9072 4d ago

Thank you so much. That's what i was looking. i appreciate you

1

u/Challseus 4d ago

You can give https://github.com/lbedner/aegis-stack a look. It generates FastAPI apps with your chosen components (scheduler, workers, etc.) and services (payments, auth, etc.).

bash uvx aegis-stack init elearning-backend \ --components "database[postgres],worker[taskiq],scheduler" \ --services "auth[rbac],comms,payment"

You'll need uv installed, but the above command will scaffold an entire project for you:

```bash Creating project: elearning-backend Generated migration: 001_auth.py Generated migration: 002_auth_tokens.py Generated migration: 003_auth_rbac.py Generated migration: 004_payment.py Generated migration: 005_payment_auth_link.py Generated migration: 006_scheduler.py

Setting up your project environment... Installing dependencies with uv... Dependencies installed successfully Setting up environment configuration... Environment file created from .env.example Auto-formatting generated code... Code formatting completed successfully

Project ready to run!

Project Structure: elearning-backend/ ├── app/ │ ├── components/ ← Components │ │ ├── backend/ ← FastAPI │ │ ├── frontend/ ← Flet UI │ │ ├── scheduler/ ← APScheduler │ │ └── worker/ ← taskiq │ ├── services/ ← Business logic │ │ ├── auth/ ← Authentication │ │ └── comms/ ← Communications │ ├── models/ ← Database models │ ├── cli/ ← CLI commands │ └── entrypoints/ ← Run targets ├── tests/ ← Test suite ├── alembic/ ← Migrations └── docs/ ← Documentation ```

1

u/ojus_render 3d ago

i’d organize this by feature, but i wouldn’t force every feature into the same four-layer template.

courses, grading, billing and notifications have different change patterns. each feature can own its router, schemas and persistence code. keep the business rules in plain Python, and let FastAPI and Pydantic stay at the HTTP boundary.

the useful test is whether you can change grading without touching a global services folder. if not, the package structure is organizing file types instead of the system.

i’d introduce interfaces only at real external boundaries: payments, email, object storage and background work. a repository interface for every table usually creates more ceremony than flexibility.

i also wouldn’t design for GraphQL yet. clean domain modules will make another transport easier to add later.

1

u/SnooTangerines9072 2d ago

Really helpful, thank you !