Why FastAPI Code Becomes Unreadable: Design Collapse in a 1,000-Line main.py

Introduction

If a circular import occurs just by splitting out APIRouter, or if it stops starting up the moment you touch lifespan, the problem isn't "line count" but "tangled responsibilities."

When you take over an API built with FastAPI,

the first file you open is inevitably just main.py.

And then you realize.

• Routing
• Authentication
• DB connection
• Dependencies
• Configuration

Everything is written in one single file.

This state is an "accident waiting to happen," even if it's "not broken yet."

---

Why does main.py become bloated?

The reason is simple:

• FastAPI is easy to write at first
• You can create something that works immediately
• Time passes while you're still thinking, "I'll split it up later"

As a result,

It's working, so don't touch it

the mentality piles up, creating a structure that no one can grasp as a whole.

---

The real problem isn't "line count"

1000 lines isn't the problem.

The problem is that

• Authentication responsibilities
• Dependency generation
• Routing definitions

These are all mixed together in the same layer.

In this state, a change in Depends can trigger

• An impact on authentication
• Taking down another endpoint along with it

Chain-reaction accidents occur.

---

The moment it becomes an "untouchable API"

The most dangerous thing about this structure is falling into a state where

It's not that you can't fix it,

but you don't know where to fix it.

As a result,

• Even if it's actually a minor fix
• No one wants to touch it
• Incident response gets postponed

And then, one day, everything breaks at once.

---

The perspective of incident response

This type of accident isn't a matter of refactoring out of the blue.

The first thing you should do is verbalize:

• Where are the dependencies being generated?
• From where to where does authentication have an impact?
• Where are the "boundaries" within main.py?

Before fixing the design, restore it to a state where the design can be explained.

This is the first step.

---

Summary

An API where main.py is bloated is

not already broken.

It is simply standing still in a state where it could break at any moment.

---

One last word

Large files are
well-suited for hiding large problems.

Note: I am conducting cause isolation for similar authentication troubles. A consultation desk is provided at the end of this article.

---

🛠️ FastAPI Incident Analysis Series

I am publishing cases where cause isolation is difficult, such as "breaking only with 401 / JWT / Docker," categorized by pattern.

🔐 Authentication/JWT Troubles

Why /token works but /me returns 401
[https://zenn.dev/fastapier/articles/0022f125547300]

Why SECRET_KEY is None even though environment variables are set
[https://zenn.dev/fastapier/articles/e93b522cc0acb3]

Confusing 401 and 403 makes the cause invisible
[https://zenn.dev/fastapier/articles/41f9e2e10e7c19]

Why Depends breaks silently resulting in 401 / 403
[https://zenn.dev/fastapier/articles/efba40f5bcbbda]

🐳 Docker/Production Environment Troubles

Why it works locally but fails only in production
[https://zenn.dev/fastapier/articles/c90e5199e0bafc]

Why logging disappeared after moving to Docker
[https://zenn.dev/fastapier/articles/cd530c54b6e47c]

---

🩺 FastAPI Incident Consultation Desk (Root Cause Identification & Structural Analysis)

Regarding authentication troubles around FastAPI / JWT / Docker, such as:

/token works but /me returns 401

InvalidSignatureError occurs only in the production environment

Authentication fails only after Dockerization

I provide cause isolation and help organize fix strategies for "incidents where the layer of the cause is hard to see."

If you haven't been able to identify the cause after more than 3 hours of investigation,
it is highly likely that the problem lies in the "structure" rather than the code.

📩 How to Contact

Please contact me via the email address listed on my GitHub profile.
[https://github.com/hiro-kuroe]

In the body of the email, please include just the following three points (short descriptions are fine):

① Symptoms
(Example: /me returns 401 / Signature error only in production / Authentication failure after Dockerization)

② Environment
(Example: Local is OK, production is NG / Using Docker / Using Gunicorn, etc.)

③ Changes made just before the issue
(Example: Changed SECRET_KEY / Added .env / Updated dependency packages, etc.)

*Note: We will start with the analysis phase (identifying the cause and organizing the structure).
Repair work will be proposed after the cause is clarified.

---