The Root of a Project

This is the starting point, and the root folder should be familiar. I've stripped away the clutter, configuration files, etc., leaving only the essentials.

• docs — An automatically generated folder containing documentation for our code. We utilize JSDoc to describe our code, and we also run a job that creates navigable HTML documentation, readily accessible for quick reference.
• reports — This folder houses all reports from unit tests, end-to-end tests, visual tests, and performance tests. We deploy all HTML reports with our code to allow visibility into test results for each version across environments.
• scripts — This contains deployment scripts, pipeline files, and other tools supporting our build processes.
• src — The core of our source code, which we will delve into further below.
• tests — Here, you'll find all scripts, configurations, helpers, utilities, and other resources required for various testing types, consolidated in one location.
• public — This folder holds our code post-build, ready for release.

High-Order Folders (Applications)

Apologies, I just had to use the term “high-order.” It adds a certain flair to the title!

All our applications reside within a monorepo (one for the frontend and another for the backend). The contents of the root/src folder organize the code by application first.

Each folder corresponds to a distinct deployable application, with Core holding a unique position as it is never deployed.

• Core — The standout application. Each app incorporates Core, which serves shared functionalities. It encompasses essential styling (grid, style utilities, etc.), design system components, reusable elements, and templates. Beyond visual components, it also manages libraries and provides JavaScript utility functions like tracking, authentication, and API integrations. All code is rigorously unit-tested to ensure consistency across applications. Once built, changes to reusable code are rare.
• Admin — This application aids in managing users, businesses, data, sales, and other administrative tasks to support our services.
• Client — The frontend applications utilized by our customers, forming the backbone of our business and the largest component here.
• DesignSystem — A dedicated application showcasing all design system components (think of it as a custom Storybook). Its purpose is to share reusable components with the business and other teams, ensuring they know how everything currently appears. It assists frontend engineers in accessing component examples, obtaining implementation code (without diving into the actual source), and saving time. Additionally, we utilize the DesignSystem app to conduct visual tests on each release to detect UI changes and errors.
• Developers — This application serves as a Developer Platform for our customers, mirroring the Client application but catering to a different audience.

This architecture is highly scalable, providing isolation between applications while facilitating easy code sharing. When developing the Developer platform recently, I set up the skeleton in just two days, thanks to the build, test, and deployment updates.

> There will never be a scenario where code from the Client is directly integrated into the Admin. Each application possesses its own code alongside everything from Core.

Some companies opt for a separate repository for each application, only to regret that choice upon reaching a certain complexity level. This method incurs significant overhead in testing, hampers rapid deployments, heightens certain risks (while mitigating others), and creates hidden dependencies and backward compatibility issues. In our case, every engineer can update a design system component without hopping between different codebases and can quickly deploy changes across applications.

Our backend application structure closely mirrors the frontend, ensuring scalability and flexibility for various applications and use cases.

In-App Folders and Their Purpose

Let’s delve into a typical application folder. Note that Core resembles this structure but lacks elements like routes or views since it is not a public-facing standalone application. Moving between application folders feels intuitive, allowing for easy navigation.

Every application requires an entry point, and since this is a SPA, we have the app.js starter along with a solitary HTML file.

• assets — This folder includes additional resources required for the application, such as logos and images used in various places. You may also find an "assets" folder in any component or view folder for more localized resources.
• components — These are reusable components across the entire application. Each subfolder is dedicated to a single component, potentially containing additional folders for tests, assets, and languages. Each component folder features an index.vue/jsx file as the entry point (a crucial aspect, albeit it may seem odd).
• composables — This folder holds reusable, state-aware logic for Vue/React. Currently, it contains limited content, but it’s kept separate from components or modules due to different functionalities.
• lang — A translations folder housing all reusable text across applications. Each component or view typically has its own lang folder for additional strings. This approach helps keep translations distinct from the code itself.
• modules — JavaScript-only code that can be reused throughout the application (there's also a modules folder in Core) and does not necessitate styles or HTML. This includes utilities, data transformation code, custom tracking implementations, etc.
• static — This contains static assets and pages that should be deployed with the application but are not directly utilized by the main code. Examples include a 404 page, access denied page, or even a "Not Supported Browser" error page.
• store — All Vue/React store files are centralized, as none are closely tied to a specific component or view (and they shouldn't be). The store is divided into smaller files by purpose, such as user, business, products, reports, etc. Each file is designed for ease of maintenance and use across the entire application.
• tests — End-to-end tests are crafted in Playwright to cover the application's top-level functionality. You'll find /test folders distributed among views and components, targeting specific areas and functionalities.
• views — This encompasses all pages viewable within the applications. Subfolders typically align with the previously described structure, often containing subfolders for assets, local components, and tests. Each folder includes router configuration for the respective view, which is why we don’t maintain a top-level router folder.

Quirks and FAQs

• Using Core — We consolidate all imports from Core into a single import, minimizing clutter and avoiding import chaos in each file. All Core functionalities — utilities, components, design system, etc., are accessible under the Core.xxx namespace.
• Design System — Although all design system components are part of Core, we also maintain a separate application that functions as a custom Storybook for previewing and testing all components.
• Always using index.js/vue/jsx — This practice designates the entry file for each component or view, ensuring we know exactly where to begin when navigating folders. For instance, we have one complex component that deviates from this rule (due to past errors), making it challenging to identify the "root" file each time.
• Remove all content rule — Every view or component folder is self-contained. If we discard a specific functionality and a view becomes unnecessary, deleting the folder will also remove all associated files like translations, styles, assets, tests, routes, etc.; these files aren’t scattered across multiple folders. This prevents situations where removing a feature leaves behind irrelevant files.
• No cross-folder imports — If a view contains components, these are not utilized externally. A component can only be employed by views within its designated area.
• No cross-app imports — Similar to the above, this rule applies to applications. The Client will never import anything from the Developer app. It’s that straightforward.
• Files as classes — All component and view file names are capitalized to align with class naming conventions. Imports in JavaScript behave similarly to singleton classes; hence, we strive for consistency. I’m still uncertain if this was the best decision, but that’s the direction we’ve taken.
• Build process — A topic for another discussion. Our build process is uniquely tailored to our requirements, allowing us to construct any application at any time. Each ends up as a separate deployable package, enabling independent release cycles without mutual interference. We can also deploy everything simultaneously when necessary.

I’m sure there are additional quirks worth noting, but these seemed the most pertinent. I may add more insights after receiving feedback.

Take the Leap!

There is no one-size-fits-all solution, and the example I’ve shared may not apply to your specific projects. Ultimately, this approach could feel daunting if you don’t customize your build process or aren’t inclined towards a monorepo structure. I hope you found at least a few interesting points in how we operate at Omnevue. If you gleaned even one useful takeaway, I’ll consider this article a success.

Feel free to reach out with any questions, and I’ll do my best to respond and clarify!