# Filesystem Layout
Nodewood projects have a specific layout that enables the Cascading Filesystem that makes it so easy to override Nodewood files and functionality with your own when needed. Generally, similar things are grouped together, but not so much that you end up with a single folder with dozens of Controllers. Instead, Nodewood uses Feature-based Development to help organize your code without simply clumping together every file of a similar kind.
Take a moment to familiarize yourself with the folder structure of a Nodewood project, as it will make it a lot easier to navigate and create your own features and code.
# Root folder
# app
This is where your application code will live. A template is used to initially populate this, but from then on, it is up to you to develop as you choose. This folder is the top of the Cascading Filesystem, which means that any file you place in this folder that duplicates a file in the same location in the wood folder will be included instead of that file.
# wood
This is where the base Nodewood code lives. This code is replaced every time you upgrade your Nodewood installation with nodewood up, so avoid making changes to files in this directory. If you want to extend or override Nodewood code, eject that file instead, and modify the ejected file.
# www
This is for your sales website. This is initially shipped with only a sample file in www/dist, but you can replace that folder with whatever you want the user to see when they land on your domain, or build it dynamically from the www/src folder.
# Shared folders
The following folders are common between the app and wood folders.
# api
This folder contains code for the back-end API of your application, which is an Express (opens new window) server. Generally, you won't put too much code directly in this folder, and instead will place it inside feature folders.
# config
Your application's configuration is stored in this folder. Secrets, however, should not be kept in this folder. Instead, they should be kept in your application's .env file in the root, and included in these files when necessary with process.env.SECRET_NAME. This ensures that this folder and your application configuration can be committed to your source control without also committing (and thus compromising) your application's secrets.
# docker
This folder contains configuration for building Docker (opens new window) containers for development.
# features
The majority of your application code will live in this folder, provided you are following Feature-based Development. Every feature folder is like a miniature application to itself, with its own api, lib, and ui folders, where your back-end, shared, and front-end code lives, respectively.
# lib
This is where shared code that is neither strictly associated with the front-end or back-end lives. Since Nodewood is written entirely in JavaScript, you can make use of Shared Code like this to speed up development and maintenance of your code.
# migrations
Nodewood uses Knex.js (opens new window) for its incredible migrations tool (though not for its query builder), and those migrations go in this folder. This is the one folder not subject to Nodewood's Cascading Filesystem. Any files placed in app/migrations whose name duplicates one in wood/migrations will cause an error.
# ui
This folder contains code for the front-end UI of your application, which is build on the Vue.js (opens new window) framework. Generally, you won't put too much code directly in this folder, and instead will place it inside feature folders.
# wood-only folders
The following folders are only in the wood base folder.
# templates
When you use the nodewood add feature, the files added to your application are templated from files residing in this folder. Generally, you'll never need to interact with this folder, only the files created from the templates within.
# api folders
The following folders are optional, but can be found in any of the api folders, including inside of features.
# controllers
Controllers, from the viewpoint of classical MVC (opens new window) live in these folders. Nodewood will load the files in these folders, examine the routes defined in their constructors, and build the routing table for your API.
# emails
Templates for Emails that you send to customers are stored here, as EJS (opens new window) templates.
# services
Typically, you will want Controller functions to be as light-weight as possible, and the logic instead be stored in libraries, models, and services. These Services are stored here, and usually perform the database and mail functions for your application, but other third-party services should be marshaled from within Services as well. In short, if you're doing a fair chunk of work, start that work from a Service, and break out what makes sense into lib folders.
# lib folders
The following folders are optional, but can be found in any of the lib folders, including inside of features. You are not limited to using only these folders, and storing common functionality in files in the root of a lib folder is frequently an excellent way to encourage code reuse.
# models
Your application's Models are stored here. These aren't traditional ORM models, and in fact don't have any database access at all (look to Services for that). Instead, Nodewood Models are common objects and collections of code that can be used in both API and UI logic.
# validators
Instead of manually writing validation code, you can use Nodewood's Validators to quickly build this logic and then use it for validating both form and API endpoints.
# ui folders
The following folders are optional, but can be found in any of the ui folders, including inside of features.
# dialogs
Any modal Dialogs you create for your application should be placed in here.
# pages
The Nodewood UI has an outer template that displays the sidebar menu and the user profile menu, then displays Pages within the rest of the body. Those pages should be stored here, and are analogous to visual Controllers -- they're the entry point for users wishing to interact with your UI.
# stores
Nodewood uses Vuex (opens new window) for state management in its UI, which is based around the concept of Stores. Those stores are placed here.