Fortress API

Overview

This repository is the official BE service for Fortress

Project structure

.
├── cmd
│   └── server
├── docs
│   ├── adr
│   ├── changelog
│   ├── diagram
│   ├── specs
│   ├── docs.go
│   ├── swagger.json
│   └── swagger.yaml
├── migrations
│   ├── schemas
│   ├── seed
│   └── test_seed
├── pkg
│   ├── config
│   ├── constant
│   ├── contracts
│   ├── controller
│   ├── handler
│   ├── logger
│   ├── model
│   ├── mw
│   ├── request
│   ├── routes
│   ├── service
│   ├── store
│   ├── templates
│   ├── utils
│   ├── view
│   └── worker
├── CODEOWNERS
├── dbconfig.yml
├── devbox.json
├── devbox.lock
├── docker-compose.yml
├── Dockerfile
├── go.mod
├── go.sum
├── Makefile
├── README.md
└── tools.Dockerfile

How to contribute

Setup local development environment (pick one of following ways)

Using DEVBOX

1. Create isolated shell using devbox

make shell

2. Start Colima as container runtime

make colima-start

Related issue when initiating development environment first time using colima

• docker-credential-desktop not installed or not available in PATH
  • tltr: Cheating by removing credsStore in the ~/.docker/config.json. Or installing osxkeychain

Using your machine environment

1. Install Golang

2. Install Docker

How to run source code locally

1. Set up source

Set up infras, install dependencies, etc.

make init

2. Set up env

Create a file .env with these values:

DB_HOST="127.0.0.1"
DB_PORT="25432"
DB_USER="postgres"
DB_PASS="postgres"
DB_NAME="fortress_local"
DB_SSL_MODE="disable"
ALLOWED_ORIGINS="*"
ENV=dev
DEBUG=true
JWT_SECRET_KEY=JWTSecretKey

3. Run source

make dev

The service starts with port 8080 as the default

How to work on a TODO

1. Feel free to pick any TODO for you from Board View
2. Assign that item to your account
3. Remember to update item’s status based on your working progress
   • Not Started: not started yet
   • Planned: working on this sprint
   • In Progress: still working on
   • In Review: Task done = PR has been merged to develop branch at least
   • Complete: Confirmation from the team that the TODO is finished

PR template

#### What's this PR do?

- [x] Add new routes for user
- [x] Add instruction for using docker-compose

#### What are the relevant Git tickets?

// Put in link to Git Issue

#### Screenshots (if appropriate)

// Use [Licecap](http://www.cockos.com/licecap/) to share a screencast gif.

#### Any background context you want to provide? (if appropriate)

- Is there a blog post?
- Does the knowledge base need an update?
- Does this add new dependencies which need to be added to?

Technical Document

Project structure

• cmd/ this folder contains the main application entry point files for the project
• docs/: contains Swagger documentation files generated by swaggo
• migrations/: contains seeds and SQL migration files
  • schemas/: contains DB schema migration files
  • seed/: contains seed files which will initialize DB with sets of dummy data
  • test-seed/: also seed files but for test DB
• pkg/: contains core source code of service
  • config/: contains configs for application
  • handler/: handling API requests
  • logger/: logging initial and functional methods
  • model/: DB model structs
  • mw/: middleware
  • request/: API request models
  • routes/: API routing (see gin)
  • service/: contains interaction with external services (google API, etc.)
  • store/: data access layers, contains DB CRUD operations (see gorm)
  • utils/: utility methods
  • view/: API view models

Sample usecases

1. Create new API

• Check out file /pkg/routes/v1.go and explore the code flow to see how to create and handle an API
• Remember to annotate handler functions with swaggo. Then run make gen-swagger to generate Swagger documentations

2. New DB migration

Check out .sql files under /migrations to write a valid schema migration / seed file

• To apply new migration files, run make migrate-up
• To apply seed files, run make seed-db
• To apply new migration files for test DB, run make migrate-test

Note: remember to run these 2 every time you pulling new code

make migrate-up
make migrate-test

3. DB repositories

Check out dirs under /pkg/store

4. New API Implementation Steps

• Add the new route to /pkg/routes/v1.go
  • Check if the new route is in a new group or an existing one
    • Implement interface IHandler in pkg/handler/[name]/interface.go
    • Implement handling functions that takes a *gin.Context in pkg/handler/[name]/[name].go
    • Add Swagger doc to handler
    • Add the sub handler to the main handler in pkg/handler/handler.go
  • Check if the new route needs authentication
  • Check if the new route needs authorization (permission)
    • If a new permission is needed then define it in pkg/model/permissions.go
• Add the new table
  • Create new migration by make migrate-new
  • Add seed file to migrations/seed
  • Include the new seed file in migrations/seed/seed.sql
  • Check if existing seed data needs modification (roles.sql, permisions.sql, etc.)
  • Implement the model in pkg/model
  • After the model is defined, implement the CRUD functions in pkg/store
    • Implement interface IStore in pkg/store/[name]/interface.go
    • Implement the details in pkg/store/[name]/[name].go
    • Add the sub store to the main store in pkg/store/store.go
• Glue the implemented handler and the implemented store

🙏 Credits

A big thanks to all who contributed to this project!

If you'd like to contribute, please contact us.