Building Web Apps: File and Directory Structures

Organization is key to making any type of code work efficiently, and this is especially true for web applications. Many web developers choose to go the route of using premade coding frameworks, such as CodeIgniter for PHP, which help them to stick to a specific structure as well as help them code quicker by providing organization in other areas. With or without a framework though, web applications need structure, and it’s best for developers to know best practices for organizing a web app’s structure from the core.

Each developer may have their own standards for how to organize a web application, but in this article we’ll go over some best practices, common practices, and cover in more detail why certain aspects of a web application should be organized in a certain way over others. Finally, we’ll also look into why organizational structure can be so beneficial when creating an application.

What Files Will You Need?

When I first began as a developer, I made the all too common mistake of just opening up my favorite IDE and coding from scratch. I quickly learned, especially for larger projects, that I should have planned ahead. Part one of planning ahead is figuring out what files you will be needing, considering what each will do, what information or functionality it will hold, and most importantly, how all the files you intend to create will work together to form the overall application.

Image credit: sonrisaelectrica

Forget directory structure for now — think only about the files you will need. For the sake of example we’ll be talking about building a PHP based application. Try to write out and begin to organize what files will be needed, and when doing so also think about how they will work together. Below are a few questions to ask about your web app:

• What classes will you need?
• Will you need other types of PHP-based scripts? (Like for validation)
• How will you handle your templating system?
• What types of content/basic page types will your web app hold?
• Will you be using a lot of StyleSheets, JavaScripts, or AJAX? If so, what files will you need?
• What will you need for admin files?

When I’m listing out the files I’ll need, I tend to simply place them in a word editing document, and place each file I’ll think I’ll need under bullets. I do, to an extent, use sub-lists and a tabbed structure to begin to think about directory structure, but I never make anything concrete until I can really think about directory structure separately.

An Example

Say we’re building a simple membership system for referral pages. Members can sign up, create their profile, upload images, and send relevant people their profile link to check out some information about their work.

What types of files will be needed to set up?

• index.php // our homepage that our website will first direct to
• content.php // a template for all of our static content pages
• memberList.php // a template for a list of members
• profile.php // a template for each member’s profile to abide by
• profileEdit.php // a template where members can edit their profile
• style.css // will hold our styles
• Images:
  • // Here will be all of our images for our design
  • profilePics/ // A folder for all of our member profile pics
  • uploads/ // A folder for all of our member uploads
• JavaScripts:
  • // Any JS files will go here, based on what we need
• Classes:
  • Member.php // A class to represent a member
  • MemberFunctions.php // A class to handle all the functions a member will do
  • Content.php // A class to handle our content functions

You may realize that you’ll need more files and think of them along the way. Having a list like this to easily edit is much better than rearranging an entire web app that’s already been primarily coded. This is just the start of an example list, but remember that it’s meant to be revised, added to, and so on along the way as you continue through the planning process.

Refining Directory Structure

From creating a list of files that you’ll need to use from above, you may already have some sort of basic directory structure going. From there on, you’ll need to further refine a directory structure for the web app, and double check to make sure that:

• There is a logical and easy to find place for every file.
• Files are organized in a way that will help code be reused efficiently.
• The files that need to reference each other can do so easily.

In this section we’ll go over some of the basics that many web developers use for directory structure, and some other best practices based on certain situations.

Image credit: maxlinkc

Nearly all web apps should at least have the following folders, if independent from a coding framework. If using a framework, these types of folders will likely already be present or have some solution in place.

• images/ — An images folder will not only hold all images for your web apps design, but also any other images that may come into play, such as profile picture uploads, member uploads, admin images, and more. This is the simplest form of organizing images, yet some directory structures may take more thought. What does your templating system look like? Perhaps you’ll want an “images/” folder for each template (like WordPress), and a separate folder for all member uploads. Maybe you’ll only have one template and you can use the same images folder, and take advantage of sub-folders. Finding a good image directory structure is essential, no matter how it’s set up, make it simple yet organized for your particular app’s situation.
• css/ — You can call this folder “styles”, “css”, “stylesheets”, or whatever. The point is it will hold all of your CSS files. Out of habit primarily, I tend to put my main stylesheet in my root directory, as that’s what I’ve gotten used to from creating WordPress themes. I then place any other stylesheets (for specific plugins, print stylesheets, responsive stylesheet, etc.) into my CSS folder.
• classes/ — Chances are if you’re creating a web app, it will be object-oriented to an extent. (It should be anyway.) Object-oriented applications will have objects that represent a feature on your site, such as a “Member” class. In essence, they are just files that group together similar functions. I sometimes build simple applications that only have one class, and others where I’ll have several. Either way, placing it in a folder for classes will help to keep things organized, especially if you need to add or delete any classes throughout the course of the app’s existence.
• includes/ — Many developers will rather call this folder “inc_” or just “inc”, although you can really call it whatever you like. The point of this folder is for any other files that will need to be included regularly into files of any type. This is a great place for a file that create a database connection, or a file that defines all of your website’s constants, like database credentials, a base URL, and so on. Many developers also like to include a configuration file here.

These are pretty much the basics for directory structure, and if not building an application from scratch, any framework will have its own solution for where to put files under each of these categories. How one developer structures their code may be completely different from another developer, and some may choose to separate their markup from code entirely with a very specific set of rules, while others can mix and match how their app code mingles with the design related code throughout the site.

Below we have a few other considerations for directory structure, that dependent on how you’d like to organize your web app, can be helpful:

• views/ – I use a “views” folder in just about every application I code from scratch. Within this views folder is where templates can be kept. If you have a templating system that would allow your web app to use several themes, this is a good folder to have. Otherwise, I tend to keep any file that holds markup specific to a particular page view here. In a sub-folder within it, I also keep any include files, such as a header.php, sidebar.php, footer.php, etc. Other developers like to make a “master page”, with all of the header, footer, and static content in one file, while there is a placeholder for the content area that will change. Whichever templating system you use is up to you, and also based on how large the application will be.
• Model-View-Controller – This is a pre-defined structure for creating web applications, and it is what the majority of coding frameworks use. Even if you aren’t using a framework, you can still follow this structure to organize your code, and separate the logic from the design. The best part about using MVC is that as it’s gaining popularity, more developers are abiding by the structure and therefore it can create consistency among many developers that may work on the same project. For more information on MVC, check out this article: MSDN: Model-View-Controller.
• Subdirectories — Creating directories in directories can make things get complicated fast, if you create too many of them. However, they can be of much needed help if files do need to be further categorized. Feel free to always use subdirectories when organizing site files, but also make sure they’re logical and needed. The bigger the web app is, the more likely you’ll need subdirectories.
• admin/ – There will likely be an administration area for about any type of web application, and it’s smart to place everything involved with administration in a separate folder. This way, an admin can access the area by directing their browser to that folder, and furthermore it’s much easier to create privacy restrictions based on the admin folder. If the admin section is mixed among all of the other files, it can be easier to forget to secure a certain page, folder, or section. By securing a separate admin folder, all subdirectories and files will be protected too.

Finally, after you’ve decided on a directory structure based off of your web application’s needs, you can create a more logical structure for your users when it comes to URL’s. In the base root of any web application, always have a .htaccess file that can rewrite (using mod rewrite) your URLs. You can use your .htaccess file to do two very important things: hide file extensions, and rework the “directory structure” for the URL to something more user friendly. Doing so will help SEO out tremendously, as well as give your users something easier to link to.

For example, our literal directory structure may link to a member’s profile page like below:

http://yourwebsite.com/app/views/profile.php?memberName=JohnnySmith

For the sake of SEO and having a member wanting to more easily link to their profile, we could use mod rewrite in our .htaccess file to turn the above URL into:

http://yourwebsite.com/profile/JohnnySmith

…or even…

http://yourwebsite.com/JohnnySmith

Getting Specific with Functionality

Before I ever like to begin coding, I always go through each of my agreed upon files and through my directory structure, and I begin to organize what the inside of those files will look like. I’ll define the variables, functions, and what those functions will do inside each of my classes, without actually writing out their code. I’ll go into each of my templates and define what will be shown on this page, and how it will retrieve the information for the page. I make sure I know before I get too into things that all of my files are able to connect with the other files and do as planned as efficiently as possible.

Below is an example of what you can do when thinking about specific functionality. There may be functionality that you are reminded of, and you’ll remember that you need to include a certain file. (Perhaps you forgot a file for your constants and database connection above!)

Often times by doing this, we can find logical errors in our structure, or find a way to rearrange things that will make it easier to reuse code. This is a great way to determine what files and structure will be most beneficial by starting to write out the pseudo-code, without actually having to “write out the code.”

Simply go through each file and in comments type out the logic first. If the logic all makes sense and you still have all the bases for you web app’s functionality covered, chances are you won’t be regretting the file and directory structure you committed to.

public class Member{
	// Variables for member info
	// Constructor: include database connection
	// Deconstuctor
	// function setInfo()
	// function getInfo()
	// function login()
	// function register()
}

public class MemberFunctions{
	// Variables
	// Constructor: include database connection
	// Deconstuctor
	// function uploadProfilePic()
	// function uploadImage()
	// function editProfile()
	// function editAccountInfo()
}

Conclusion

The thing I dislike about coding frameworks is that their structure may not be what’s best for each application that is built off of it. This is particularly true for small applications that don’t need all those bulky files, yet at the same time a coding framework’s strict guidelines for structure can be beneficial in many situations. When it comes to creating your own web app from scratch, do some initial planning as above in order to determine in the first place whether a coding framework would be beneficial.

Regardless of frameworks, planning a web app’s structure can make any sort of web app more efficient and better organized. Good organization will make the application quicker (as it will reuse code more efficiently), be easy to add onto or edit if need be, and be easier to work with for another developer.