work on structure docs

documentation.md

@@ -6,6 +6,7 @@
 - Setup
     - [Installation](/docs/{{version}}/installation)
     - [Configuration](/docs/{{version}}/configuration)
+    - [Directory Structure](/docs/{{version}}/structure)
     - [Homestead](/docs/{{version}}/homestead)
     - [Valet](/docs/{{version}}/valet)
 - Tutorials
@@ -23,8 +24,6 @@
     - [Views](/docs/{{version}}/views)
     - [Blade Templates](/docs/{{version}}/blade)
 - Architecture Foundations
-    - [Request Lifecycle](/docs/{{version}}/lifecycle)
-    - [Application Structure](/docs/{{version}}/structure)
     - [Service Providers](/docs/{{version}}/providers)
     - [Service Container](/docs/{{version}}/container)
     - [Contracts](/docs/{{version}}/contracts)

structure.md

@@ -1,8 +1,26 @@
-# Application Structure
+# Directory Structure
 
 - [Introduction](#introduction)
 - [The Root Directory](#the-root-directory)
+    - [The `app` Directory](#the-root-app-directory)
+    - [The `bootstrap` Directory](#the-bootstrap-directory)
+    - [The `config` Directory](#the-config-directory)
+    - [The `database` Directory](#the-database-directory)
+    - [The `public` Directory](#the-public-directory)
+    - [The `resources` Directory](#the-resources-directory)
+    - [The `storage` Directory](#the-storage-directory)
+    - [The `tests` Directory](#the-tests-directory)
+    - [The `vendor` Directory](#the-vendor-directory)
 - [The App Directory](#the-app-directory)
+    - [The `Console` Directory](#the-console-directory)
+    - [The `Events` Directory](#the-events-directory)
+    - [The `Exceptions` Directory](#the-exceptions-directory)
+    - [The `Http` Directory](#the-http-directory)
+    - [The `Jobs` Directory](#the-jobs-directory)
+    - [The `Listeners` Directory](#the-listeners-directory)
+    - [The `Notifications` Directory](#the-notifications-directory)
+    - [The `Policies` Directory](#the-policies-directory)
+    - [The `Providers` Directory](#the-providers-directory)
 
 <a name="introduction"></a>
 ## Introduction
@@ -12,41 +30,105 @@ The default Laravel application structure is intended to provide a great startin
 <a name="the-root-directory"></a>
 ## The Root Directory
 
-The root directory of a fresh Laravel installation contains a variety of directories:
+<a name="the-root-app-directory"></a>
+#### The App Directory
 
-The `app` directory, as you might expect, contains the core code of your application. We'll explore this directory in more detail soon.
+The `app` directory, as you might expect, contains the core code of your application. We'll explore this directory in more detail soon; however, almost all of the classes in your application will be in this directory.
 
-The `bootstrap` directory contains a few files that bootstrap the framework and configure autoloading, as well as a `cache` directory that contains a few framework generated files for bootstrap performance optimization.
+<a name="the-bootstrap-directory"></a>
+#### The Bootstrap Directory
 
-The `config` directory, as the name implies, contains all of your application's configuration files.
+The `bootstrap` directory contains files that bootstrap the framework and configure autoloading. This directory also houses a `cache` directory which contains framework generated files for performance optimization such as the route and services cache files.
+
+<a name="the-config-directory"></a>
+#### The Config Directory
+
+The `config` directory, as the name implies, contains all of your application's configuration files. It's a great idea to read through all of these files and familiarize yourself with all of the options available to you.
+
+<a name="the-database-directory"></a>
+#### The Database Directory
 
 The `database` directory contains your database migration and seeds. If you wish, you may also use this directory to hold an SQLite database.
 
-The `public` directory contains the front controller and your assets (images, JavaScript, CSS, etc.).
+<a name="the-public-directory"></a>
+#### The Public Directory
+
+The `public` directory contains the `index.php` file, which is the entry point for all requests entering your application. This directory also houses your assets such as images, JavaScript, and CSS.
+
+<a name="the-resources-directory"></a>
+#### The Resources Directory
+
+The `resources` directory contains your views as well as your raw, un-compiled assets such as LESS, SASS, or JavaScript. This directory also houses all of your language files.
 
-The `resources` directory contains your views, raw assets (LESS, SASS, CoffeeScript), and localization files.
+<a name="the-storage-directory"></a>
+#### The Storage Directory
 
-The `storage` directory contains compiled Blade templates, file based sessions, file caches, and other files generated by the framework. This directory is segregated into `app`, `framework`, and `logs` directories. The `app` directory may be used to store any files utilized by your application. The `framework` directory is used to store framework generated files and caches. Finally, the `logs` directory contains your application's log files.
+The `storage` directory contains your compiled Blade templates, file based sessions, file caches, and other files generated by the framework. This directory is segregated into `app`, `framework`, and `logs` directories. The `app` directory may be used to store any files generated by your application. The `framework` directory is used to store framework generated files and caches. Finally, the `logs` directory contains your application's log files.
 
-The `tests` directory contains your automated tests. An example [PHPUnit](https://phpunit.de/) is provided out of the box.
+The `storage/app/public` directory may be used to store user-generated files, such as profile avatars, that should be publicly accessible. You should create a symbolic link at `public/storage` which points to this directory. You may create the link using the `php artisan storage:link` command.
+
+<a name="the-tests-directory"></a>
+#### The Tests Directory
+
+The `tests` directory contains your automated tests. An example [PHPUnit](https://phpunit.de/) is provided out of the box. Each test class should be suffixed with the word `Test`. You may run your tests using the `phpunit` or `php vendor/bin/phpunit` commands.
+
+<a name="the-vendor-directory"></a>
+#### The Vendor Directory
 
 The `vendor` directory contains your [Composer](https://getcomposer.org) dependencies.
 
 <a name="the-app-directory"></a>
 ## The App Directory
 
-The "meat" of your application lives in the `app` directory. By default, this directory is namespaced under `App` and is autoloaded by Composer using the [PSR-4 autoloading standard](http://www.php-fig.org/psr/psr-4/).
+The majority of your application is housed in the `app` directory. By default, this directory is namespaced under `App` and is autoloaded by Composer using the [PSR-4 autoloading standard](http://www.php-fig.org/psr/psr-4/).
+
+The `app` directory contains a variety of additional directories such as `Console`, `Http`, and `Providers`. Think of the `Console` and `Http` directories as providing an API into the core of your application. The HTTP protocol and CLI are both mechanisms to interact with your application, but do not actually contain application logic. In other words, they are simply two ways of issuing commands to your application. The `Console` directory contains all of your Artisan commands, while the `Http` directory contains your controllers, middleware, and requests.
+
+> {tip} Many of the classes in the `app` directory can be generated by Artisan via commands. To review the available commands, run the `php artisan list make` command in your terminal.
+
+<a name="the-console-directory"></a>
+#### The Console Directory
 
-The `app` directory ships with a variety of additional directories such as `Console`, `Http`, and `Providers`. Think of the `Console` and `Http` directories as providing an API into the "core" of your application. The HTTP protocol and CLI are both mechanisms to interact with your application, but do not actually contain application logic. In other words, they are simply two ways of issuing commands to your application. The `Console` directory contains all of your Artisan commands, while the `Http` directory contains your controllers, middleware, and requests.
+The `Console` directory contains all of the custom Artisan commands for your application. These commands may be generate using the `make:command` command. This directory also houses your console kernel, which is where your custom Artisan commands are registered and your [scheduled tasks](/docs/{{version}}/scheduling) are defined.
+
+<a name="the-events-directory"></a>
+#### The Events Directory
 
 The `Events` directory, as you might expect, houses [event classes](/docs/{{version}}/events). Events may be used to alert other parts of your application that a given action has occurred, providing a great deal of flexibility and decoupling.
 
-The `Exceptions` directory contains your application's exception handler and is also a good place to stick any exceptions thrown by your application.
+<a name="the-exceptions-directory"></a>
+#### The Exceptions Directory
+
+The `Exceptions` directory contains your application's exception handler and is also a good place to place any exceptions thrown by your application. If you would like to customize how your exceptions are logged or rendered, you should modify the `Handler` class in this directory.
+
+<a name="the-http-directory"></a>
+#### The Http Directory
+
+The `Http` directory contains your controllers, middleware, and form requests. Almost all of the logic to handle requests entering your application will be placed in this directory.
+
+<a name="the-jobs-directory"></a>
+#### The Jobs Directory
+
+The `Jobs` directory houses the [queueable jobs](/docs/{{version}}/queues) for your application. Jobs may be queued by your application or run synchronously within the current request lifecycle. Jobs that run synchronously during the current request are sometimes referred to as "commands" since they are an implementation of the [command pattern](https://en.wikipedia.org/wiki/Command_pattern).
 
-The `Jobs` directory, of course, houses the [queueable jobs](/docs/{{version}}/queues) for your application. Jobs may be queued by your application or run synchronously within the current request lifecycle.
+<a name="the-listeners-directory"></a>
+#### The Listeners Directory
 
-The `Listeners` directory contains the handler classes for your events. Handlers receive an event and perform logic in response to the event being fired. For example, a `UserRegistered` event might be handled by a `SendWelcomeEmail` listener.
+The `Listeners` directory contains the classes that handle your [events](/docs/{{version}}/events). Event listeners receive an event instance and perform logic in response to the event being fired. For example, a `UserRegistered` event might be handled by a `SendWelcomeEmail` listener.
+
+<a name="the-notifications-directory"></a>
+#### The Notifications Directory
+
+The `Notifications` directory contains all of the "transactional" notifications that are sent by your application, such as simple notifications about events that happen within your application. Laravel's notification features abstracts sending notifications over a variety of drivers such as email, Slack, SMS, or stored in a database.
+
+<a name="the-policies-directory"></a>
+#### The Policies Directory
 
 The `Policies` directory contains the authorization policy classes for your application. Policies are used to determine if a user can perform a given action against a resource. For more information, check out the [authorization documentation](/docs/{{version}}/authorization).
 
-> {note} Many of the classes in the `app` directory can be generated by Artisan via commands. To review the available commands, run the `php artisan list make` command in your terminal.
+<a name="the-providers-directory"></a>
+#### The Providers Directory
+
+The `Providers` directory contains all of the [service providers](/docs/{{version}}/providers) for your application. Service providers bootstrap your application by binding services in the service container, registering events, or performing any other tasks to prepare your application for incoming requests.
+
+In a fresh Laravel application, this directory will already contain several providers. You are free to add your own providers to this directory as needed.