# File Structure

* `.next` - the default build directory used by Next.js.
* `components` - library of custom, reusable Rock Mountain components
* `docs` - documentation (all written in markdown and linked to from the main `README.md` page in the project root); note that this is currently being phased out in favor of using the GitHub wiki
* `lib` - internal JS code libraries and utilities
  * `aws-ses-client.js` - uses the Amazon Web Services (AWS) SDK to deliver email through AWS Simple Email Service (AWS SES). This is what is used presently for sending email via the Contact page and form.
  * `gtm.js` - a function for sending a pageview to Google Tag Manager.
  * `mongodb.js` - a client lib that uses the MongoDB Node.js API for establishing a connection to the database. Within the file, it is commented that "global is used within to maintain a cached connection across hot reloads in development. This prevents connections growing exponentially during API Route usage."
* `mongodb-migrations` - contains database scripts within subfolders matching package version numbers that should be executed to migrate existing data using the [MongoDB for VS Code](https://marketplace.visualstudio.com/items?itemName=mongodb.mongodb-vscode) extension. Inside each script, we start with `use('rm_preview');` and we change it to `use('rm_production');` when we are manually executing the migration. We know, therefor, that any script beginning with `use('rm_production');` has already been run on the production database and that migration is complete already.
* `mongodb-playgrounds` - contains database scripts that can be executed using the [MongoDB for VS Code](https://marketplace.visualstudio.com/items?itemName=mongodb.mongodb-vscode) extension.
* `node_modules` - all node dependencies defined in `package.json` are stored here when you run `npm install` or `npm i`.
* `pages`
  * `admin` - this folder establishes the `/admin` URL route. Any and all administrative pages should go under here.
    * `posts` - this folder establishes the route for administering posts or documents or content; we're not yet 100% sold on the name, "posts" because this is not strictly a blog engine and we're not sure we should lean so much into that metaphor.
      * `[slug].js` - Create or Update Content Form. This page component establishes the dynamic route, `/admin/posts/*`. The slug that is passed in should be the existing or desired slug (e.g. `_id` from MongoDB) of the document.
    * `style-guide.js` - this is probably a temporary page, but for now, it's used to experiment and log any guideleines for the emerging style (look-and-feel).
  * `api` - in Next.js anything placed under this route is intended to create RESTful API endpoints, thus all of our RESTful API endpoint handlers can be found within.
    * `posts` - this folder establishes the API route for administering posts or documents or content; we're not yet 100% sold on the name, "posts" because this is not strictly a blog engine and we're not sure we should lean so much into that metaphor.
      * `[slug].js` - Create or Update Content REST handler. This API endpoint establishes the dynamic route, `/api/posts/*`. The slug that is passed in should be the existing or desired slug (e.g. `_id` from MongoDB) of the document.
    * `send-mail.js` - REST API endpoint for submitting email throught the Amazon Web Services Simple Email Service (depends on/uses: `lib/aws-ses-client`).
  * `books` - temporary route for a page in our test-case blog, `codyburleson.com`; this will be taken away as everyhting beomes more dynamic and database-driven.
    * `cage.js` - temporary page in our test-case blog, `codyburleson.com`; this will be taken away as everyhting beomes more dynamic and database-driven.
  * `_app.js` - This App component is the top-level component which is common across all the different pages. You can use this App component to keep state when navigating between pages, for example. See: [Custom App](https://nextjs.org/docs/advanced-features/custom-app)
  * `_document.js` - See: [Custom Document](https://nextjs.org/docs/advanced-features/custom-document)
  * \[...path.js] - The main view page. Dynamic routes can be extended to catch all paths by adding three dots (...) inside the brackets, which is what this file is doing. Unless some other file or set of files matchg a router path, all other paths (even with multiple path segments) are caught by this one controller file. Inside, we parse out the web page slug and we use that as a unique id for fetching content for the view.
  * `blog.js` - Blog page (in primary navigation)
  * `books.js` - Books page (in primary navigation)
  * `contact.js` - Contacts page (in primary navigation)
  * `index.js` - Home page (currently not used in our test-case blog, codyburleson.com, but may be used in the future)
  * `search.js` - Search page (displays search results from the global search form in the navbar; currently uses a simple form of Programmable Search Engine by Google)
* `public` - static resources that should always be public such as images and icons.
  * `images` - any images related to the core platform/engine can go here, but images related to the blog contents are currently stored in an AWS S3 bucket.
    * `profile.jpg` - a temporary image remaining from an early demo app; I don't think we're using it except on the index.js (Home) page, so it can probably be removed soon.
  * `ads.txt` - If your serving up Google Ads on your site, Google gets fussy if this file is not in place.
  * `favicon.ai` - Adobe Illustrator master file for generating the Favorite Icon(s)
  * `favicon.ico` - favorite icon file (the icon shown on the web browser tab when a page is open)
  * `robots.txt` - standard robots.txt file for search engines. If this is not here, everytime a crawler hits the site, you get unecessary noise in request logs that the resource is not found
* `styles` - cascading style sheets
  * `global.css` - the global stylesheet which sets styles across all pages, sitewide. It is global because it is imported in the `pages/_app.js` file.
* `.env.local` - File containing all possible environment variables. Some may be secret, so when this file exists, it is NOT commited to the Git repository.
* `.env.local.example` - Example file containing all possible environment variables; this exists soley to be copied and renamed to `.env.local`.
* `.gitignore` - Defines the folders and files that should be ignored (i.e. that should NOT be commited to the Git repository)
* `jsconfig.json` - Specifies the root files and the options for the features provided by the JavaScript language service. The file can optionally list the files belonging to the project, the files to be excluded from the project, as well as compiler options. See [Visual Studio Code jsconfig.json](https://code.visualstudio.com/docs/languages/jsconfig). In addition to its use for VS Code, it's needed for the Next.js [Absolute Imports and Module path aliases](https://nextjs.org/docs/advanced-features/module-path-aliases) feature. Notes: jsconfig.json can be used when you don't use TypeScript, otherwise you need to use tsconfig.json. You need to restart dev server to reflect modifications done in this file.
* `next.config.js` - For configuring custom advanced behavior of Next.js.
* `package-lock.json` - is automatically generated for any operations where npm modifies either the `node_modules` tree, or `package.json`. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates. This file is intended to be committed into source repositories, and serves various purposes. See: [package-lock.json documentation](https://docs.npmjs.com/cli/v6/configuring-npm/package-lock-json)
* `package.json` - the Node Package Manager configuration file which defines all the Node dependencies used by the application. When the command `npm install` or `npm i` is used, a `node_modules` folder is created in the project root and the dependencies are downloaded into it. This file also contains the application version number, which should be updated for every new release. This can be updated manually, or by using the command: `npm version <update_type>` where update type is one of `patch`, `major`, or `minor` (following the [semantic versioning](https://docs.npmjs.com/about-semantic-versioning) system). The footer of the application always displays this version number. It does so by importing, `const pjson = require('package.json');`, and then printing with `{pjson.version}`. This is currently done in `components/layout.js`.
* `README.md` - this is the file you're reading right now.
* `vercel.json` - configuration file containing options that changes the default behavior of the Vercel platform. See: [Vercel Configuration Reference](https://vercel.com/docs/configuration)
