Unmaintainable code rarely arrives as one dramatic mistake. It accumulates: a god module here, a copy-pasted rule there, a shared mutable object everyone reaches into. Six months later every change feels risky, onboarding takes weeks, and nobody wants to touch the core files. The good news is the warning signs show up early—if you know what to look for.
This checklist is for teams building with React/Next.js, Laravel, PostgreSQL, Redis, and ERP-style systems. Use it in a code review, a retrospection, or a quiet Friday architecture walk. If three or more signs feel familiar, schedule a structure review before the next feature sprint.
1. God Modules That Do Everything
A single file—or a single class—owns routing, validation, business rules, database access, and email. In Laravel it often looks like a 2,000-line controller. In React it is a page component that fetches, transforms, caches, and renders everything.
// Red flag: one module owns the world
export async function OrderPage() {
const orders = await db.query('SELECT * FROM orders...');
const priced = applyDiscounts(orders);
await redis.set('orders:list', JSON.stringify(priced));
return <OrderTable rows={priced} />;
}
Split by responsibility. UI renders. A service prices. A repository queries. That separation is the same instinct behind controller vs service vs repository.
2. Unclear Module Boundaries
You cannot draw a box around "billing" without pulling in inventory, auth, and reporting. Imports cross domains freely: InventoryService calls InvoiceCalculator, which imports StockLevel again. When boundaries are fuzzy, every feature becomes a cross-cutting change.
Healthy boundaries name a capability and expose a small public API. Everything else stays private to that module.
3. Circular Dependencies
Module A imports B, B imports C, C imports A. Bundlers warn, Laravel's service container gets confusing, and TypeScript circular types force awkward import type workarounds. Cycles usually mean two concepts should be one—or a third shared kernel should own the shared types.
- Watch for mutual imports between feature folders
- Prefer dependency direction that flows inward toward domain types
- Extract shared DTOs instead of reaching across features
4. Copy-Paste Explosion
The same validation, status mapping, or discount rule appears in five places with small drift. Fixing a bug means hunting files. This is the opposite of good abstraction—and it is one of the habits that separates short-lived code from work that lasts, as discussed in junior vs senior developer code.
// Same rule pasted in API, job, and admin form
if ($order->status === 'paid' && $order->total > 0) {
// ... slightly different each time
}
Extract once you have a second real use case—not a hypothetical plugin framework.
5. Fear of Changing Code
Engineers avoid certain directories. "Don't touch BillingService." "We work around legacyCheckout." Fear is a structure signal: the module has too many responsibilities, too few tests, or hidden side effects. Track which files people route around in PR descriptions—that map is your refactor backlog.
6. Tangled Shared State
Global stores, request-scoped singletons, and Redis keys that every feature reads and writes without ownership. In React, a mega-context or a chain of effects that keep each other in sync is the same smell—see why too many useEffect hooks are a code smell.
// Shared bag everyone mutates
appStore.set('currentTenant', tenant);
appStore.set('pricingRules', rules);
// ... 40 other keys, no owner
Prefer explicit props, typed services, and keys namespaced by module with a clear writer.
7. Missing Layer Ownership
Nobody agrees where logic belongs. Controllers call the database. Repositories send emails. Blade or React components know SQL column names. Without layer ownership, every new hire invents a new path from request to persistence.
Document a thin convention: HTTP adapters → application/services → domain → persistence. Keep it boring. Structure that stays boring is how teams survive years of new requirements.
8. Inconsistent Folder Conventions
One feature lives under components/orders, another under features/Order, a third under pages/api/v2/orderStuff. Laravel apps sometimes mix app/Services, app/Actions, and app/Domain with no rule for which goes where. Inconsistency taxes every search and every review. Pick one layout for new code and migrate hot paths gradually—the same advice as in structuring a large React project.
9. Tests That Are Hard to Write
If writing a unit test requires booting the full app, seeding half the ERP schema, and mocking twelve globals, structure is fighting you. Hard-to-test code usually has tangled constructors, hidden statics, or logic buried in framework lifecycle hooks.
- Pure domain functions should test without HTTP
- Repositories should be swappable behind an interface when needed
- UI should receive data props, not reach into the database
When tests become easy, refactors become safe—and fear drops.
10. Onboarding Takes Weeks
A capable developer needs two weeks to land a small change because the mental map of the system is tribal knowledge. That is not a hiring problem; it is a structure and documentation problem. Clear modules, consistent folders, and owned layers shrink onboarding more than any wiki page.
What To Do When Several Signs Apply
- Pick one painful module—not the whole codebase.
- Draw its real dependencies (imports, Redis keys, tables).
- Extract one boundary: a service, a repository, or a feature folder.
- Add characterization tests around the behavior you must not break.
- Repeat on the next hotspot after the next release.
Incremental structure work beats a freeze-the-world rewrite. Measure progress by fear: fewer "don't touch that" comments, faster PR reviews, and onboarding that takes days instead of weeks.
Conclusion
Unmaintainable structure announces itself through god modules, fuzzy boundaries, cycles, copy-paste, fear, shared state, missing ownership, messy folders, untestable seams, and slow onboarding. You do not need all ten to act. Catch the pattern early, restore clear boundaries, and keep shipping features on a codebase you can still change.