diff --git a/learning-the-code.md b/learning-the-code.md new file mode 100644 index 0000000..0a8cb27 --- /dev/null +++ b/learning-the-code.md @@ -0,0 +1,66 @@ +# Learning the Code + +The best way to become familiar with the codebase is to start making something with it! + +However, if you're exploring the codebase by yourself, I recommend first learning the core technologies, at least to a basic level: + +* React +* Nodejs +* MariaDB (with Sequelize) +* Docker (with docker-compose) + +# Core Server + +Next, you can have a quick look at the express server under `server/`. I've tried to keep it simple, but it DOES have a placeholder database connection which is unused. It also switches any browser requests for JS and CSS files to return the gzip files instead (this is a little trickery to reduce bandwidth); these files are generated by webpack. + +# Core Client - app.jsx + +Under `client/pages/` you'll find `app.jsx`, which is the main switchboard for the template's different webpages. By default, it has enough pages hooked up to serve a simple website that you can interact with. Each route uses `LazyRoute`, which is used in place of `Route` to enable code-splitting (yet another trick to reduce bandwidth). + +The routes have two different ways of loading a page: + +```js + import('./accounts/login')} /> + + () => } /> +``` + +The former loads a react-driven page, while the latter loads a Markdown driven page (these pages have HTML embedding enabled). + +Finally, at the bottom of the switch there is a ternary expression which optionally renders the `PopupChat` component if the user is logged in (i.e. the browser has an accessToken). + +# Core Client - Default Pages + +Account and administration pages are separated into their own directories, while the landing pages are stored in the same directory as `app.jsx`. + +`homepage.jsx` is shown when the user is logged out - every default page redirects here if the user is logged out. + +`dashboard.jsx` is shown when the user is logged in - pages that shouldn't be seen when logged in also redirect to `homepage.jsx`, which in tern redirects here. + +`not-found.jsx` is used when the specified page can't be found. + +# Core Client - Styling + +There are two CSS files provided for styling the template under `client/styles/` - `popup-chat.css` is intended ONLY for the popup chatbox, while `styles.css` is intended to be augmented by other stylesheets (but can be replaced entirely, if desired). Most of styles.css uses flexbox, and it's actually mobile- and tablet-friendly. + +There are a few specific CSS classes I'd like to point out: + +`central` - This creates margins on the sides of the page, while leaving room for the footer. + +`page` - This is intended for top-level react page components. + +`panel` - This is intended for individual UI elements within a `page` - these can be nested. + +`centered` - this will, in theory, center one of the above classes along it's long-axis. Also works on `text`. + +`middle` - this is the complement for `centered`, and will center on of the above classes along it's short-axis. + +`constrained` - used for form components that are restricted to the middle of the page. + +`table`, `table row`, `table row col` - this is a flexbox table system. Can be used in divs or real table elements for positioning. + +`mobile show` - hides the element, except on mobile. `tablet show` is also available. + +`mobile hide` - does nothing normally, but hides the element on mobile. `tablet hide` is also available. + +"mobile" is defined as screen width of 480 pixels, while "tablet" is defined as 768 pixels. \ No newline at end of file