Single File Location and Structure/alx

From Open Pattern Repository for Online Learning Systems
Jump to navigation Jump to search

Single File Location and Structure
Contributors Roland Bijvank, Wiebe Wiersema, Christian Köppe
Last modification May 17, 2017
Source Bijvank, Wiersema & Köppe (2013)[1]
Pattern formats OPR Alexandrian
Learning domain


Files are an established mechanism used by applications to store and retrieve configuration, libraries, state, data etc. Newly developed applications tend to use files in their own unique manner and store files in various locations. This may lead to having files that are dispersed over different folders or hidden in system-folders of the Operating System. System administrators want to be able to perform version control on the files.


Problem and forces:

Having dispersed files causes system administrators to have difficulty in finding the files necessary for their tasks during the life cycle of an application.

—Distributed Applications.

Many applications consist of different subsystems, which often require subsystem-specific administration tasks. These subsystems are in many cases developed by different teams, resulting in dispersed groups of similar artifacts for each subsystem. This situation is well suited for developers as they can work in parallel. During deploy or system administration activities this can be a burden because of the way they have to look in different locations.

—Hard-coded Locations.

It happens often that developers put the location of the configuration files in source code and provide no parameters or interface to influence this location. This means the path can only be changed by building and deploying a new version of the application. Running multiple instances of a program on a machine with different parameters is effectively blocked by this approach. Additionally it can pose security risks if the file location is in a privileged location such as C:\Program Files for Windows based systems.


When a file of a module isn’t used anymore it will easily remain in disuse and get overlooked which causes pollution of your hard disk.


Therefore: Put all related files in a folder hierarchy relative to one location on a file system or repository. Make the path of this location configurable.

Solution description:

Analyze the files and folders of the application, group the files that logically belong together and should be at the same location in a folder e.g.: the binaries of a system, the configuration files and the data files. In the case of log files one should first consider to use Centralized System Logging (Centralized System Logging).

Ideally it should be a structure that is re-used across applications (see figure 1) that are installed on the same server. This provides consistency for the system administrator, but also might help to overcome possible redundancies of files (e.g. keeping track of the language used). It furthermore serves as a clear guideline for the developers and could also be included in a reference architecture.

For reading the contents of configuration files Property Loader (Property Loader) and related patterns[2]can be used.

If an application is deployed several times on a server it may be necessary to include the name of each specific application instances in the path on the file system. E.g. use /somewhere/theapp/internal and /somewhere/theapp/external if an application instance is deployed once for internal users and once for external users on the same server. This will separate the files for each application deployment. A common practice in these cases is to a symbolic link to share common files across all deployed instances.

Single File Location and Structure-alx 01.png
Fig. 1 The hierarchical file structure

The applications that do file access should not use the native File IO Libraries but should use a Facade (Facade)[3] for accessing files (see figure 2). This Facade (Facade) provides the basic file IO functionality and prohibits absolute path access. The Facade (Facade) is using a configurable absolute path that is the root of all file access. The relative paths branch from that root path. This is best enforced in combination with a build server that checks which libraries are used from source code. The build should break when native File IO Libraries are used instead of the library that provides the Facade (Facade).

If the folder structure to be used for applications is standardized across a development group, developers find it easier to navigate across an application and find the right files and folders. This can also be supported by providing skeleton solution or projects structures within the development environments such as Eclipse or Microsoft Visual Studio.

Single File Location and Structure-alx 02.png
Fig. 2 Main solution structure for file access using Single File Location (Single File Location)


When not using this pattern the files of applications will be dispersed over several distinct locations which makes it hard to maintain the application.

Using Single File Location and Structure (Single File Location and Structure) is also more secure as this blocks access to other parts of the filesystem on the server as the implemented Facade (Facade) blocks access outside the root location. It is somewhat similar to a jailshell which is widely used to constrain linux users within their homefolder.

A nice example of the structure of Single File Location and Structure (Single File Location and Structure) without a Facade (Facade) is for instance found in the way applications based on the Ruby on Rails (RoR) framework[4] are structured. Every project starts with a pre-defined folder and file structure. RoR organizes all models, view and controller related logic in model, view and controller folders. Alle configuration settings are stored in a configuration folder and the Development, Test and Production stages related settings are stored in subfolder of the configuration folder. The framework provide internal relative paths to these folders so application can be stored in any location as long as the structure within the application folder remains the same.

Another example is the Filesystem Hierarchy Standard[5]. FHS defines the directory structure and directory contents in Unix and Unix-like operating systems, maintained by the Linux Foundation. Most Linux distributions follow the Filesystem Hierarchy Standard and maintain FHS compliance. Similar constructs are found in how OSX organizes applications and application data in file hierarchy.


  1. Bijvank, R., Wiersema, W., & Köppe, C. (2013). Software architecture patterns for system administration support. In Proceedings of the 20th Conference on Pattern Languages of Programs (PLoP 2013) (p. 1). The Hillside Group.
  2. Wellhausen, T., Wagner, T., & Müller, G. (2010). Handling Application Properties.
  3. Gamma, E., Helm, R., Johnson, R., & Vlissides, J. (1994). Design Patterns: elements of reusable object-oriented software. Addison-Wesley: Boston, MA.
  4. Rails. (2014). Ruby on Rails. Accessed: 25-04-14.
  5. FHS. (2014). Filesystem Hierarchy Standard. Accessed: 25-04-14.