Episode 3: How the Codebase Is Organized (What Lives Where and Why)
You've hired a talented NetSuite developer. On day one, they clone the repository, open the project, and freeze. There are folders everywhere, business logic scattered across three different places, and nobody can explain where new code should go.
Poor codebase organization doesn't just slow down onboarding—it compounds technical debt, creates deployment risks, and turns every feature request into a guessing game.
Let's talk about how to structure NetSuite projects so your team can move fast without breaking things.
A Quick Note Before We Start
The folder structures and architecture patterns we'll discuss are examples of how we typically organize projects. They illustrate principles, not rigid rules.
Different teams, SuiteApps, or legacy systems may adjust naming, contents, and layering as needed.
What stays consistent:
- Clear entry points
- Separation of concerns
- Maintainable layering
- Predictable business logic flow
Don't fixate on exact folder names. Focus on the intent behind them.
Why Codebase Organization Actually Matters
Clean architecture isn't about perfectionism. It's about sustainable velocity.
When your NetSuite codebase has clear structure, developers can:
- Find existing logic quickly instead of rewriting functionality that already exists
- Know exactly where new code belongs without consulting senior developers
- Debug confidently by following predictable patterns
- Onboard in days, not weeks because the system makes sense
- Ship features faster because they're not fighting the architecture
Chaos feels faster in the moment. Structure wins over time.
A Practical Framework for NetSuite Projects
Here's how we structure our NetSuite codebases. Your exact folder names might differ, but what matters is the thinking behind them.
/src — The Brain of Your Application
Everything meaningful happens here. We use a Clean Architecture-inspired approach to keep code readable, testable, and maintainable.
- Think of
/src
as the organized workspace where business logic, data access, and system integration all have their designated places.
/src/controller — Your Entry Points
Controllers map directly to NetSuite script types:
- Suitelets
- RESTlets
- User Events
- Map/Reduce scripts
- Client Scripts (when needed)
Controllers exist to receive requests and route them correctly. They validate input, call the appropriate use case, and return formatted output. That's it.
Example: GenerateBillPayment.controller.ts validates payment data → calls the use case → returns a structured response.
Controllers should never contain business logic.
/src/usecase — Your Business Logic Layer
If logic reflects a functional rule or business process, it belongs here.
Use cases answer: "What should happen in the system based on business requirements?"
They orchestrate steps, apply rules, combine operations, and coordinate between gateways.
Example: MatchBillLines.usecase.ts evaluates PO versus Bill lines → enforces matching logic → returns results.
Use cases make your business rules explicit and testable.
/src/gateway — Your Data & Integration Layer
Gateways handle anything external to your application logic:
- NetSuite record operations
- SuiteQL queries
- External REST APIs
- FileCabinet interactions
- Third-party integrations
Examples:
- VendorPaymentGateway.ts — manages vendor payment records
- FileStorageGateway.ts — handles FileCabinet operations
Gateways keep your use cases clean and free from API noise. They're also the easiest parts to mock during testing.
/src/presenter — Your Output Formatting Layer
Presenters translate internal results into consumer-friendly formats:
- API JSON responses
- UI dropdown data
- Suitelet page content
- Success/error messages
- Structured RESTlet output
They ensure use cases never worry about "frontend-friendly" formatting or client-specific response shapes.
/src/domain — Your Shared Language
Domain defines the shape of your entire project:
- Interfaces and types
- Enumerations
- Shared constants
- Data models
- Reusable domain objects
This folder eliminates:
- Magic strings scattered across files
- Duplicate type definitions
- Random enums hidden in business logic
- Inconsistent data structures
When everyone uses the same domain definitions, communication improves and bugs decrease.
/scripts or /deploy — Your NetSuite Output
This is where compiled, deployable files land for NetSuite.
Engineers should never manually edit files here. Let your build process and CI/CD pipeline handle it.
This separation keeps source code clean and deployment predictable.
/tests — Your Quality Layer
Tests reinforce engineering discipline and accelerate onboarding.
Our testing standards:
- One describe block per method
- Clear it( ) statements that read like documentation
- Mock gateways, not real NetSuite records
- Verify business logic, not external API behavior
- No unnecessary comments—tests should be self-explanatory
Good tests keep onboarding smooth because new engineers learn expected behavior by reading them.
What NOT to Do
Even with good intentions, certain patterns will undermine your codebase organization:
- Don't mix business logic into controllers. It makes testing impossible and hides important rules.
- Don't let use cases access records directly. Use gateways to keep data access isolated.
- Don't create random "helpers" or "utils" folders. Every piece of code should have a clear architectural home.
- Don't duplicate logic. If functionality exists somewhere, use it. Don't rewrite it.
- Don't override the architecture because it's faster. Technical debt compounds.
- Don't turn /src into a junk drawer. When everything goes "somewhere in src," you've lost all organizational benefits.
Architecture Is Culture
Good codebase organization isn't about making your GitHub repository look impressive. It's about building shared understanding so your team can collaborate effectively.
When developers know where everything belongs and why, they contribute with confidence. Onboarding accelerates. Features ship faster. Technical debt stays manageable.
That's the difference between a project and a system.
Let's Talk About Your NetSuite Development Organization
Struggling with codebase chaos or slow developer onboarding? ATSOURCE helps NetSuite development teams establish sustainable architecture patterns and collaborative practices that scale.
Contact us to discuss how we can help your team build cleaner, more maintainable NetSuite solutions.
Meet the Author
Jona has over a decade of experience in SuiteCloud Development on the NetSuite platform. She specializes in implementing advanced solutions and has led teams in creating high-quality software. Jona holds multiple certifications and has been recognized with awards like the Summit Award and Quality Champion Award.
Tags
Accelerate ERP Success with Expert Solutions
Ready to put what you've learned into practice? ATSOURCE delivers both the specialized talent and comprehensive NetSuite support you need to turn strategy into results.Connect with our experts today and move from planning to performance.
