Router File Splitting

Overview

BlueClerk's backend code is organized into smaller, focused files to improve maintainability and development speed. This "file splitting" approach keeps related functionality together while preventing individual files from becoming too large to navigate or debug effectively.

Why File Splitting Matters

Developer Benefits

• Faster navigation - Find relevant code quickly without scrolling through thousands of lines
• Easier debugging - Smaller files mean clearer stack traces and faster issue isolation
• Better code review - Reviewers can focus on specific feature areas without overwhelming context
• Reduced merge conflicts - Changes to different features rarely touch the same file

File Organization Strategy

BlueClerk splits backend code by:

• Feature domain - Customer queries, job operations, invoice actions
• Operation type - Queries vs mutations vs helper functions
• Shared types - Common TypeScript types used across multiple files

Common Split Patterns

Router Files

Large tRPC routers are split into:

• Query files - Read operations (customer-queries.ts, ticket-queries.ts)
• Mutation files - Write operations (invoice-actions.ts, estimate-actions.ts)
• Helper files - Shared logic (job-queries-mine-helpers.ts)
• Type files - TypeScript interfaces (estimate-action-types.ts, worker-job-detail-types.ts)

AI Tool Files

AI chat tools are organized by:

• Catalog operations - Item search, creation, updates (chat-tools-catalog-mutations.ts)
• Core mutations - Invoice/estimate/ticket creation (chat-tools-mutations.ts)
• Helper utilities - Customer linking, deduplication logic

Frontend Components

UI components split by:

• Feature boundaries - Invoice prompts, job detail modals
• Shared types - Component prop interfaces
• Modal content - Dialog components separated from page components

What This Means for You

If You're a User

You won't notice file splitting directly - it's a behind-the-scenes improvement. What you WILL notice:

• Faster bug fixes - Developers can locate and fix issues more quickly
• More reliable features - Smaller files mean fewer unintended side effects from changes
• Smoother updates - Less risk of breaking unrelated features during deployments

If You're a Developer

When contributing to BlueClerk or reviewing code:

• Check existing patterns - Follow the split structure already in place
• Keep files focused - If a file grows beyond ~500 lines, consider splitting
• Use descriptive names - File names should clearly indicate what they contain
• Maintain imports - Update import paths when files are reorganized

Questions

Q: Why not just keep everything in one big file? A: Large files (2000+ lines) become unmanageable - finding specific functions takes longer, merge conflicts are more common, and it's harder to reason about what the code does. Splitting improves both developer experience and code quality.

Q: Does file splitting affect app performance? A: No. File organization is a development-time concern - the production build bundles everything efficiently regardless of how source files are structured.

Q: How do I know which file contains the code I need? A: Look at file names and folder structure. Queries go in -queries.ts files, mutations in -actions.ts or -mutations.ts, and shared types in -types.ts. When in doubt, search the codebase by function or component name.