Frontend System Design · Lesson 18 of 86 · 4 min
Structuring a Large Single-Page App
This question tests if you can think beyond a single component and plan for a codebase that scales with the team and the product.
In an interview, you'll be asked to design a system. For a large app, your first decision is how to organize the files. Get this wrong, and every subsequent decision is harder to implement. There are two main paths. One is a dead end for large projects.
The Core Trade-off: Grouping by Type vs. Grouping by Feature
The default for small projects is grouping files by their technical type. You have a top-level components/ folder, a services/ folder, a hooks/ folder, and so on. This is simple to start with, but it doesn't scale. As the app grows, these folders become junk drawers with hundreds of unrelated files. Finding all the code for a single feature—like user authentication—requires jumping between five different directories.
The professional standard for large applications is grouping by feature, also called domain-driven or vertical-slice architecture. All the code for a single feature lives together in one folder. The auth feature has its own components, hooks, and API calls. The products feature has its.
This approach creates high cohesion (related code is together) and low coupling (features don't depend on each other's internal details). It's easier to maintain, easier for teams to work in parallel, and easier to delete old features.
How to Implement a Feature-Based Structure
Your source code should be split into two main top-level directories: features/ and shared/.
features/ contains folders for each business domain, like auth, product-search, or user-profile. Each feature folder is a mini-application, containing everything it needs to function.
shared/ contains code that is truly generic and has no knowledge of any specific business domain. This is for things like your design system (Button, Input, Modal), generic hooks (useLocalStorage), and base API clients.
The trap: A common mistake is putting domain-specific components into shared. If a component knows what a "product" or a "user" is, it is not a shared component. ProductCard belongs in features/products, not shared/ui. The moment a component makes an API call to a specific endpoint or renders data with a specific shape, it has become feature-specific.
In an interview, clearly distinguishing between
featuresandsharedis critical. Explain thatsharedcode must be business-agnostic. This demonstrates you understand how to create and enforce boundaries, which is key to long-term maintainability.
A Realistic Code Structure
Here’s what this structure looks like in practice. Notice how the LoginPage uses both a feature-specific component (LoginForm) and a generic, shared component (Button).
The directory might look like this:
src/
├── features/
│ └── auth/
│ ├── components/
│ │ └── LoginForm.tsx
│ ├── services/
│ │ └── authApi.ts
│ └── pages/
│ └── LoginPage.tsx
└── shared/
├── ui/
│ └── Button.tsx
└── api/
└── baseApi.ts
First, the truly reusable button in the shared directory. It knows nothing about what it's used for.
// src/shared/ui/Button.tsx
import React from 'react';
interface ButtonProps {
onClick: () => void;
children: React.ReactNode;
variant?: 'primary' | 'secondary';
disabled?: boolean;
}
export const Button: React.FC<ButtonProps> = ({ onClick, children, variant = 'primary', disabled = false }) => {
const baseStyle = "px-4 py-2 rounded font-semibold";
const variantStyle = variant === 'primary' ? "bg-blue-500 text-white" : "bg-gray-200 text-black";
const disabledStyle = disabled ? "opacity-50 cursor-not-allowed" : "";
return (
<button
className={`${baseStyle} ${variantStyle} ${disabledStyle}`}
onClick={onClick}
disabled={disabled}
>
{children}
</button>
);
};
Next, the login page, which lives inside the auth feature. It imports the shared Button from a stable, external path but imports its own logic and components using relative paths.
// src/features/auth/pages/LoginPage.tsx
import React, { useState } from 'react';
import { Button } from '../../../shared/ui/Button'; // Import from shared
import { login } from '../services/authApi'; // Import from within the feature
// Assume LoginForm is defined in ../components/LoginForm.tsx
import { LoginForm } from '../components/LoginForm';
export const LoginPage: React.FC = () => {
const [error, setError] = useState<string | null>(null);
const [isLoading, setIsLoading] = useState(false);
const handleLogin = async (credentials: { user: string, pass: string }) => {
setIsLoading(true);
setError(null);
try {
const { token } = await login(credentials);
localStorage.setItem('authToken', token);
// Redirect or update state
} catch (err) {
setError('Login failed.');
} finally {
setIsLoading(false);
}
};
return (
<div>
<h1>Login</h1>
{error && <p>{error}</p>}
<LoginForm onSubmit={handleLogin} isLoading={isLoading} />
</div>
);
};
This structure makes dependencies explicit. The auth feature depends on shared, but not on products. You can change or even delete the products feature without any risk of breaking authentication.
How to Answer "Design a Large SPA"
When asked how you'd structure a large frontend application, state your preference for a feature-based structure and justify it using the right keywords.
"For a large-scale application, I would use a feature-based, or domain-driven, directory structure. I'd create a top-level
features/directory containing self-sufficient modules for each business domain, like 'user-profile' or 'product-search'.This promotes high cohesion and low coupling. It scales well because adding a new feature is just adding a new folder, without modifying existing ones. It also improves team autonomy, as different teams can own different feature folders with fewer merge conflicts.
To handle cross-cutting concerns, I'd establish a
shared/directory for truly generic, business-agnostic code. This would include our design system components, core utilities, and a base API client. The rule is simple: if it knows about a specific business domain, it does not belong inshared.This structure also naturally supports performance optimizations like code-splitting, as we can lazy-load entire feature modules on demand."
This answer is confident, covers the key benefits (scalability, maintainability, team velocity), and shows you've considered the practical details, like the role of a shared directory and the potential for lazy loading.
Try it
Sketch the directory structure for an e-commerce app with products, cart, and auth features. Decide where each of these four files would go: Button.tsx, ProductCard.tsx, useAuth.ts, and apiClient.ts. Justify each placement in one sentence.
Next: We'll apply these structural ideas to individual components in Component-Based Architecture Principles.
Lock it in — apply this lesson under interview conditions.