Backend folder stucture, Item entity, and --upstream merging problem

[Toffa97]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the documentation, with the integrated search.
• I already searched in Google "How to X" and didn't find any information.
• I already read and followed all the tutorials in the docs and didn't find an answer.

Example Code

No real code here, just words

Description

I used the template in 4 different project, but in all of them I find the same problem:

• I restructure model / scheme / repos exc in separated folders, eachone about its own related element
• I remove the Item entity cause I do not need it

These 2 actions are kinda boring with git merge --upstream.

Since (my personal opinion) the division in sub folder is more optimal for a big project, why not adopt it instead of using backend/app/crud-models.py files?
Something like

backend/app/model-schema-repo/user.py

Moreover, any suggestion for the --upstream merge? Just do it by hand and do not merge the changes?

Operating System

Linux

Operating System Details

No response

Project Version

last one

Python Version

No response

Additional Context

No response

[brians930617]

I agree that for a larger project, separating the models, schemas, and repositories into modules can make the codebase easier to navigate and maintain.

For example, instead of having everything in large files like:

backend/app/models.py
backend/app/schemas.py
backend/app/crud.py

you could organize it around each domain/entity:

backend/app/
├── models/
│   └── user.py
├── schemas/
│   └── user.py
├── repositories/
│   └── user.py

or, if you prefer keeping everything related to one entity together:

backend/app/
└── user/
    ├── model.py
    ├── schema.py
    └── repository.py

I personally prefer the second approach once the number of entities grows, because changes related to one domain stay together.

For removing the Item example, I would avoid fighting the upstream template every time. If Item is only example/demo code and your project doesn't need it, removing it locally makes sense.

For upstream merges, I would keep your project-specific changes as isolated as possible. Then when you pull changes from the template:

git fetch upstream
git checkout main
git merge upstream/main

If the template changes files that you have substantially reorganized, Git cannot always determine that the changes belong to their new locations, so some manual conflict resolution is expected.

Another option is to treat the template as a starting point rather than something that you continuously merge. Once your project has diverged significantly, manually reviewing the important upstream changes can be much less painful than repeatedly trying to merge the entire template.

So I think the best approach depends on how closely you want to track the template: if you want frequent upstream updates, minimize structural divergence; if your project has become substantially customized, maintaining your own structure and selectively applying useful upstream changes may be simpler.

[Vedant021004]

To add to @brians930617's good points on domain organization, here are concrete Git and project strategies to eliminate the recurring friction with --upstream merges when you remove Item and reorganize the folder structure:

---

Why the Conflicts Happen

When you delete Item and split monolithic files (models.py, crud.py, etc.) into sub-packages, Git's 3-way merge sees:

• Upstream: modified backend/app/models.py (e.g., added a field, formatting update, or type hints).
• Your branch: deleted backend/app/models.py (or moved it elsewhere).

This produces recurring modify/delete and rename/modify merge conflicts on every single upstream pull.

---

Strategy 1: Use .gitattributes with the ours Merge Driver

If you want to continue running git merge upstream/main without git stopping on deleted or replaced template files, you can configure Git to automatically favor your local version for those specific files.

1. Enable the ours merge driver in your local Git config:

   git config merge.ours.driver true

2. Create or update .gitattributes in your repository root:

   # Never let upstream overwrite your custom model/route structure
   backend/app/models.py merge=ours
   backend/app/crud.py merge=ours
   backend/app/api/routes/items.py merge=ours

Now, whenever you run git merge upstream/main, Git will automatically keep your files and ignore upstream's changes to those specific files without halting the merge with conflicts.

---

Strategy 2: "Quarantine & Unplug" instead of Hard Deleting

If you hard-delete items.py and remove references across 5 different template files (models.py, crud.py, tests/, alembic/), you create conflict surface area across all 5 files.

Instead of hard-deleting:

1. Leave the dummy files in place: Keep items.py and the Item model as-is.
2. Unplug the router: In backend/app/api/main.py, simply comment out or omit:

   # api_router.include_router(items.router, prefix="/items", tags=["items"])

Because the router is never registered, Item is dead code with zero runtime effect, but upstream merges to items.py will never conflict because you never touched the file! This reduces your conflict surface to a single clean line in main.py.

---

Strategy 3: Place Custom Business Domains in a Dedicated Package

Instead of replacing backend/app/ files in-place, put your domain entities in an isolated subfolder, e.g.:

backend/app/
├── core/            # (Template core - auth, security, config, db session)
├── api/             # (Template API routing)
└── domains/         # (YOUR project domain modules)
    └── users/
        ├── models.py
        ├── schemas.py
        ├── repository.py
        └── router.py

By keeping your code in backend/app/domains/, upstream template updates (which only touch backend/app/core/, Dockerfiles, CI, or dependency configs) will merge cleanly via fast-forward or trivial 3-way merges without touching your business logic.

---

Strategy 4: Selective Cherry-Picking instead of Branch Merges

In practice, after a project matures beyond initial scaffolding, 90% of upstream commits are unrelated to your application (or touch frontend/demo components).

Instead of merging the entire upstream branch:

git fetch upstream
# Inspect recent commits from the template maintainers:
git log --oneline main..upstream/main

If there is a specific security patch, Docker improvement, or dependency upgrade (e.g. UV or Pydantic update), simply cherry-pick that single commit:

git cherry-pick <commit-hash>

This gives you all the benefits of upstream template maintenance without any structural merge pain.