-
Notifications
You must be signed in to change notification settings - Fork 3
Project Walkthrough
Here's the TL;DR version of what goes where:
This folder holds manifest files that tell GitHub Actions how to test your code whenever you submit a pull request or push to the main branch. Generally you won't need to edit these files unless you are introducing something major like a new database or Selenium browser.
This directory caches all of your Maven dependencies so that you don't have to re-download everything every time you launch the Docker Compose stack. If you run into Maven-related issues, delete everything in this folder (except for the folder itself and .m2-cache/.keep). You shouldn't ever need to directly edit/create anything in this directory unless you REALLY break your Maven setup.
This folder contains some scripts required to set up the GitHub Actions environment. Normally you don't need to use these scripts unless you are debugging something with GHA itself. Edit these scripts if you need some special tool to be installed for your tests to pass on GitHub actions.
These files/folders are used by the ELK stack for advanced debugging and log management. See https://github.com/CS4850Group5A/VirtuDoc/wiki/Advanced-Logging for more details.
This directory contains configuration for the SSL proxy. Unless you are fixing the proxy container, you shouldn't need to edit anything in here.
This folder contains auto-generated certificates from the reverse proxy. These files are unique to your machine and can present a security risk if exposed. Never share any file in this directory with anyone for any reason. If you accidentally upload these files to GitHub, delete your local copy of these files and remove them from your system certificate store immediately.
Java classes that are annotated with @Bean or @Configuration are stored here. These are special classes that may mutate depending on what launch profile is used by Spring.
A controller maps some basic high-level logic to a specific route. For example, a controller would say "when the user goes to /emails/1/delete, delete the email with ID = 1". Controllers are also responsible for session validation and enforcing basic non-ACL security restrictions.
If you need to send a group of variables across the application, you probably need a Data Transfer Object (DTO). A DTO is just a plain Java class that holds a couple of values together. For example, if you want to send an email using the MailService, you would create an EmailDTO that contains the sender, receiver, message, images, etc.
This folder stores entitites, which are items that are stored in the database. An appointment, for example, is an entity. Note that for your objects to be stored in the database, the must be marked with @Entity.
Every entity in src/main/java/com/virtudoc/web/entity must have a corresponding repository in this directory. A repository defines what database functions are associated with a given object. The basic functions that should be implemented for almost every object are Create, Read, Update, and Delete (usually known as the CRUD model).
Generally speaking, application logic should normally go in here as a service, and not in a controller. @Service classes are instantiated once on application boot, and they are injected into controllers and other services using the @Autowired attribute on private class members.
Assets for things like CSS, JavaScript, and images should go in here.
This is where ThymeLeaf HTML templates go. These are normal HTML files, but you can add special fields using #{ ... }, and values will be injected by the controller at run-time.
These are still ThymeLeaf HTML templates, but these are used by the MailService class to send emails to users.
This is where our tests live. There are three kinds of tests.
The first kind of test is a unit test. Unit tests only test one class at a time. You can use Mockito to mock external dependencies to ensure that you are only testing the logic in your class.
The second kind is an integration test. This is where you connect one or more classes or services together and test that they work together as an isolated group. You may still need to use Mockito for some things.
The final type of test is an end-to-end (E2E) test. Like the other kinds of tests, you use JUnit to organize your tests, but you do not directly load any classes from the project source. Instead you use a WebDriver called Selenium. When you run these kinds of tests, the WebDriver will open an instance of Google Chrome on your computer, and will pretend to be a user using your website. These kinds of tests are critical, because they make sure that everything works from top to bottom when everything gets connected together. Unfortunately, these are some of the hardest tests to write, and will require an in-depth knowledge about how the front-end is designed. As of the writing of this wiki page, this is also the only way to test the frontend JavaScript code.
This contains junk from Java when building the project. The Docker stack automatically ignores this folder, as well as Git. If you get funky errors from Java while building or running the project, try deleting everything in this folder (but not the folder itself) and re-building. Unless you are doing something really weird (like running decompilers or native cross-compilers on the compiled JAR itself), you shouldn't need to edit/create/delete individual files in here.
Most of these files you do not need to work with directly, but here's an explanation of what they do:
-
.dockerignore: Tells Docker to ignore certain files when building images, reducing the overall image size. If you are using a tool that generates large files that are not relevant to the running application, add them in here. -
.gitignore: Tells Git to ignore certain kinds of files. Use caution when deleting lines from this file, as some files in your project present a security risk if you accidentally upload them. -
docker-compose.yml: Details all of the services required to run the web app locally. If for example, you want to run a disposable instance of MongoDB, run when you boot the application, this is the place to add it (please be mindful of the fact that not everyone has as fancy of a computer as you do, do everything you can to minimize the number of running services, and to use compacted Alpine images whenever possible). -
Dockerfile: Specifies how to build the Docker image for when you run the application locally. This image file is purposely not optimized so that you can quickly spin the app up and down without having to rebuild the entire application every time. Edit this file at your own peril, as it can really break the application and your local code if you don't know what you are doing. -
heroku.yml: Tells Heroku what auxiliary services to add to our application. This is commonly known as Infrastructure-as-Code. Generally there is no need to edit this file unless you are adding a new SaaS product to the stack. -
mvnw,mvnw.cmd: This is Maven Wrapper. It makes it so you don't have to manually configure Maven paths when you run Spring commands. Do not edit these files directly, unless you are upgrading Spring versions and the upgrade guide explicitly tells you to do so. -
pom.xml: Used for dependency management in Java. If you need to use an extra library or framework, this is where you add it. Pretty please remember to pin the version numbers! -
prod.Dockerfile: Specifies how to build the production Docker image. Unlike the normal Docker image stored inDockerfile, this image is highly optimized to download and boot extremely quickly when Heroku needs it. As a trade-off, the build process takes much longer (which is why it is normally performed using GHA and Heroku CI after a PR merge). Exercise extreme caution when editing this file, as it is very difficult to test without actually deploying to production!
Depending on what IDE you use, you may see *.iml, .idea, .vs, and .eclipse directories appear. You can ignore these directories, but make sure they don't accidentally get committed to GitHub, as it can mess with everyone else's IDE settings. As cool as your light theme is, I don't think everybody else wants to use it too! :)