initial commit 2

docs/wiki/01 - Definitions.md

@@ -0,0 +1,13 @@
+# Definitions
+
+## Steps
+
+- `build`: compilation and project preparation step
+- `run`: execution step
+
+## Environments
+
+- `loc`: local
+- `dev`: development
+- `stg`: staging
+- `prd`: production

docs/wiki/02 - Environments.md

@@ -0,0 +1,21 @@
+# Environments
+
+## Definitions
+
+- Local (`loc`)
+
+Your local machine.
+
+- Development (`dev`)
+
+Useful for us to test the implementation without messing with
+the partners experience.
+
+- Staging (`stg`)
+
+Used to simulate production and as homologation version.
+Works as the last step before production.
+
+- Production (`prd`)
+
+Production server.

docs/wiki/03 - Folders.md

@@ -0,0 +1,64 @@
+# Folders
+
+## Reason
+
+The goals for a common project's folder structure is to mantain the organization
+and to promote a common language between the programmers, decreasing the new
+members' learning curve.
+
+## Definitions
+
+### Structure
+
+- `domain`:
+
+  - `service`:
+    contains the business logic and persistence, i.e. validating values based on business
+    rules 
+
+  - `contract`:
+    contains the interfaces for the whole app; useful for mocking dependencies on
+    the tests and also decoupling the packages from each other, making the code independent
+    from external technologies, e.g. databases
+
+  - `entity`:
+    represents the values our domain understands
+
+- `infra`:
+  contains utilities that will be used across the whole app
+
+- `data`:
+  contains the connection with the database or any other way to do the persistence
+
+  - `data*`:
+    an "implementation"
+
+- `application`:
+  represents our application as a whole
+
+  - `applicationservice`:
+    contains the application logic, i.e. parses and validates the data received, calls
+    many domain's services, parses the output data and sends it
+
+  - `entitymapping`:
+    contains the functions that parses the application's view model to the domain's
+    entities, and vice-versa
+
+  - `viewmodel`:
+    the data that will be sent and received from the app; it differs from the entity
+    because it does not represent the values of our app, but rather the values the
+    front-end server will understand
+
+- `server`:
+  contains the definitions for the web server
+
+  - `router`:
+    defines the routes and its handlers; contains no logic, only calls the application
+    package
+
+  - `serverconfig`:
+    defines the middlewares and the server's configurations
+
+- `static`:
+  not required; mostly used for static files, such as large texts, email templates,
+  static values, etc, or temporary files (commonly in `static/temp`)

docs/wiki/04 - Dockerfile.md

@@ -0,0 +1,31 @@
+# Dockerfile
+
+## Definitions
+
+There are two `Dockerfile`s, one for each step of execution set in
+the [definitions document][definitions-doc].
+
+## Containers
+
+- Build
+
+Defined in `Dockerfile.build`
+
+Has installed every program that is needed to build the code.
+Gets the source, install the dependencies and makes the final binary
+of our app.
+
+The reason for us to have a container just for the building process is
+that it demands lots of programs and dependencies to set up the Go
+environment and build everything, which aren't needed in the server for
+our app to run. Without it, the container for the running process would
+be huge, full of useless binaries and softwares.
+
+- Run
+
+Defined in `Dockerfile.run`
+
+This is the container that will run in the servers. Contains nothing,
+but our app and what it need to make it run.
+ 
+[definitions-doc]: https://bitbucket.org/nemt/nemt-portal-api/blob/master/docs/wiki/01%20-%20Definitions.md

docs/wiki/05 - Makefile.md

@@ -0,0 +1,67 @@
+# Makefile
+
+## Reason
+
+Great to simplify and standardize commons and repetitive tasks.
+
+## Definitions
+
+Following the patterns of the [definitions document][definitions-doc], every task related to 
+the compilation os preparation of the server for execution will `build` as part of the name,
+while tasks related to the execution itself will be call `run`.
+
+## Common instructions
+
+### Build
+
+- `create-build-container`: creates the container for building, using `Dockerfile.build`
+
+- `build`: build the server inside the container and gets the binary
+
+- `build-loc`: calls `build` using local (`loc`) environment
+
+- `build-dev`: calls `build` using development (`dev`) environment
+
+- `build-stg`: calls `build` using staging (`stg`) environment
+
+- `build-prd`: calls `build` using production (`prd`) environment
+
+### Run
+
+- `create-run-container`: creates the container for execution, using `Dockerfile.run`
+
+- `run`: executes the app inside the container
+
+- `run-loc`: calls `run` using local (`loc`) environment
+
+- `run-dev`: calls `run` using development (`dev`) environment
+
+- `run-stg`: calls `run` using staging (`stg`) environment
+
+- `run-prd`: calls `run` using production (`prd`) environment
+
+- `run-host`: executes the app without a container, directly on the local host
+
+### Environment
+
+- `set-loc`: defines the environment as "local" (`loc`)
+
+- `set-dev`: defines the environment as "development" (`dev`)
+
+- `set-stg`: defines the environment as "staging" (`stg`)
+
+- `set-prd`: defines the environment as "production" (`prd`)
+
+### Database
+
+- `migrate`: executes the full migration of the database
+
+### Tests
+
+- `test`: executes the whole battery of tests
+
+### Others
+
+- `clean`: remove binaries and compiled files
+
+[definitions-doc]: https://bitbucket.org/nemt/nemt-portal-api/blob/master/docs/wiki/01%20-%20Definitions.md