Please ROAST My FastAPI Template

Posted by Hopeful_Beat7161@reddit | Python | View on Reddit | 34 comments

Source code: https://github.com/CarterPerez-dev/fullstack-template

I got tired of copying the same boilerplate across projects and finally sat down and made a proper template. It's mainly for my own use but figured I'd share it and get some feedback before I clean it up more.

What my project does:

FastAPI with fully async SQLAlchemy (asyncpg, proper connection pooling)
JWT auth with refresh token rotation + replay attack detection
Alembic migrations (async compatible)
PostgreSQL + Redis
Docker Compose setup for dev and prod
Nginx reverse proxy configs for both environments
Rate limiting via slowapi (falls back to in-memory if Redis dies)
Structured logging with structlog
Repository pattern for DB operations
Full test suite with pytest-asyncio + factory fixtures
Fully Linted (mypy, ruff, pylint)
Uses uv for package management, just for commands
Basic user auth/CRUD and basic admin CRUD

Comparison:

Did a deep dive into current best practices (+Nov 2025) for FastAPI, Pydantic, async SQLAlchemy, Docker, Nginx, and spent way too much time reading docs and GitHub issues to ensure nothing's using deprecated patterns or outdated approaches.
Also has Astral's new type checker - 'ty 0.0.1a32' setup to mess around with (Came out literally last week, so I highly doubt any similar templates have it setup).

So what I'm looking for:

Anything that looks wrong or could be done better
Stuff you'd want in a template like this that's missing
General opinions on the structure or anything else etc.

Target Audience:

Right now its just a github template but im thinking about turning this into a cookiecutter or CLI tool at some point so I and or you can scaffold projects with options. Also working on a matching frontend template (with my personal favorite stack: React TS + Vite + SCSS + TanStack Query + Zustand) that'll plug right in.

Anyway, lmk what you think, please roast it, need some actual criticism!

[-]

LifeSatisfaction5558@reddit

I've been running FastAPI + asyncpg in production for a product catalog with \~565K products and 1,347 category pages. A couple of things I learned the hard way:

If you're using parameterized queries with array filters, watch out for asyncpg's type casting. Something like WHERE id = ANY($1::int[]) can silently fail — you need to explicitly cast with ARRAY[:param]::int[] depending on how you pass the params.

Also, for SEO-heavy apps, I'd add cache headers middleware early. I ended up with nginx reverse proxy handling cache for category pages and it made a huge difference in TTFB.

Looks solid overall though!

[-]

Aromatic-Drink-9581@reddit

u can rate mines too https://github.com/AuricErgeson/fastapi-starter-template

[-]

jones-peter@reddit

Try this with Jsweb
https://github.com/Jsweb-Tech/jsweb
insted of FastAPI

[-]

MasterThread@reddit

Imports from src, no Di for repositories, those classmethods. Bruh...

[-]

KitchenFalcon4667@reddit

I second this. src/ is a unix directory like usr/, bin/, tmp/ and mnt/. It is used to show source code, coming from compile languages. It should not be part of your package or library.

In today’s vibe-coding, I see even tests.slop imports. I think we need to be more awake. Generating code is easy. Understanding code is becoming gold.

[-]

MasterThread@reddit

In python it's used for editable install.

Tiangolo don't know how to write application code. Thats some sort of doom that frameworks creators don't know how to write apps. He even made the same mistakes in fastapi documentation. And lots of junior developers say: "Wow looks cool! Let's copypaste! Straight into my project!"

[-]

Hopeful_Beat7161@reddit (OP)

Could you elaborate? Absolute imports from src work fine for applications, it's not a distributed package. Repositories get the session injected, which is the actual external dependency. And JWT for frontend... what's the alternative you're suggesting?

[-]

MasterThread@reddit

First of first, src is being used not only in dist packages. Src layout is used for more convenient imports for tests and system environment. With editable install you can run your application from anywhere as long as you have your venv activated. You made a flat structure but with src root for no reason. Second - you ruined di and layer division by using your controller with sessions and not using Protocols. Sry but those classmethods are cringe. Google hexagonal arch for beginning (ports/adapters). You can find more advanced example with clean architecture and cqrs here. There is a fully charged Di container. Third - generic repo is an antipattern for many reasons. JWT is not for frontend, but for applications such as mobile apps, desktops and client programs. For frontend, pls use sessions. Client side, or server side (better). For more info read this owasp article. As I remember, we have sessions implemented in fastapi-users. But following owasp, it will take about 200 rows to implement sessions.

[-]

Hopeful_Beat7161@reddit (OP)

Appreciate this actually useful feedback with specifics. I'll dig into the hexagonal arch resources and the OWASP article. Thanks for taking the time.

[-]

s0ftware-dev@reddit

Looks ok. Not a fan of static methods on service classes (might as well use pure functions without the class overhead) would prefer a singleton instance injected into the controller using depends which can then be mocked easily in unit tests (of which you have none).

Also a repository is a DDD concept and should really be an abstraction with an underlying database implementation. What you’ve got is a DAO which is a viable pattern but not the same thing.

Tech seems fine (Docker, Alembic etc) but core patterns are pretty rigid and won’t scale.

[-]

Hopeful_Beat7161@reddit (OP)

Static methods, it's a stylistic choice. I use classes as namespaces rather than instantiated objects. For a template, I opted for explicitness over DI ceremony. You're right that pure functions would be equivalen, the class is just organizational. Singleton injection is valid too, just a different tradeoff IMO.

Repository vs DAO, you're technically correct. What I have is closer to a DAO since it's explicitly SQLAlchemy coupled rather than an abstraction. I used "Repository" because it's the more commonly understood term in the FastAPI ecosystem, but I take your point on DDD terminology.

Thanks for the feedback!

[-]

IAMARedPanda@reddit

Modules are already namespaces. Static methods force users to import the whole class even if they only want to use one method. It's fine in application code but if I saw this in a code review I would advise to just use regular functions.

[-]

pacific_plywood@reddit

I think a lot of people are using Ty though maybe not in production

[-]

Hopeful_Beat7161@reddit (OP)

True, didn’t think many people are since it came out just last week, and no, not for production, but it’s fun to mess around with in development. (Was mainly looking for a “comparison” so I through that in the post)

[-]

AstroPhysician@reddit

It didn’t come out last week though…

[-]

Careless_Machine_221@reddit

Cool project. I might use it.

Why do you use capital letters for files in models? It's not pythonic.

Do you really need separate docker file for dev and prod? IMO you can use one and change how you run it in docker compose when running the stack.

[-]

Hopeful_Beat7161@reddit (OP)

I'm self taught (no CS degree), so I've picked up most of my habits from jobs. My first mentor/boss came from a Java background and used PascalCase for model file and I just never dropped it. Personal quirk at this point. As for separate Dockerfiles, it's just an organizational preference, i find it easier to reason about at a glance.

[-]

burger69man@reddit

one thing that'd be nice is a minimal example, like a stripped down version of the template for smaller projects

[-]

Hopeful_Beat7161@reddit (OP)

Good idea actually, might add a minimal branch with just auth + single model, no roles/token families/rate limiting. Best of both worlds.

[-]

coconut_maan@reddit

Honestly ...

In my humble and personal opinion I feel like it's not so pythonic.

Not every project will require all of this boiler plate.

Python style has always been start as simple as possible and only add complexity if necessary.

This is sort of the opposite.

[-]

Hopeful_Beat7161@reddit (OP)

You're not wrong, this is definitely opinionated and heavier than a typical starter template. Honestly, it's less "template" and more "my production baseline" that I extracted. This is the boilerplate I end up writing on every project anyway, so I packaged it.

If you're starting a small API, yeah, a single main.py with SQLModel is the pythonic move. This is more for when you already know you'll need auth, role based access, token rotation, etc etc.

Thanks for the feedback!

[-]

irungaia@reddit

Phenomenal

[-]

Hopeful_Beat7161@reddit (OP)

I have PTSD from my main project where I went overboard on unit tests and 75 tests would fail from 1 line change, so I opted for integration tests only, atleast for the template, and will scale accordingly with more sub folders.

[-]

pooogles@reddit

I dislike this as it often leads to teams saying "I don't write smoke tests, that's for X". Use pytest markers and cohost them in the same file IMO.

[-]

Basic-Still-7441@reddit

At first it looks really nice, reminds me a lot of my own setup. One difference I noticed is that I prefer to use ULID instead of UUID because ULID looks better to my eye, in the URLs etc (doesn't contain dashes like UUID). But that's a matter of taste I guess, nothing important. Good job, thanks!

[-]

Hopeful_Beat7161@reddit (OP)

Thanks!

[-]

gopietz@reddit

Cool project.

I guess my criticism would be the complexity. I don't want to start a fresh project and have my code base being so large initially.

[-]

Hopeful_Beat7161@reddit (OP)

Yea it’s very personalized to projects I make hence the complexity, which is usually my boilerplate, that’s why I’m planning on making it a cookiecutter or CLI tool so people can configure / install exactly what they need or don’t need. Thanks for the feedback!

[-]

gopietz@reddit

I'd think about incorporating something with AI too. I have a single markdown file that shows the different services and patterns I like to use in my code. I can then ask Claude Code or Codex to set up the project for me, based on a briefing or features I request.

A cookie cutter CLI tool feels a bit 2019.

[-]

panicrubes@reddit

I appreciate that you included the docs/research section to explain WHY you made the decisions you did.

I doubt I will use your template, but I definitely will look into the thought process behind each part to determine if it's right for me. Thanks!

[-]

wRAR_@reddit

I appreciate that you included the docs/research section to explain WHY you made the decisions you did.

Considering that "research" is fully AI-written it's unclear if they did any explanation or decisions themselves.

[-]