{"id":27396618,"url":"https://github.com/hmsayem/empora","last_synced_at":"2025-07-22T11:35:19.793Z","repository":{"id":43759568,"uuid":"435889885","full_name":"hmsayem/empora","owner":"hmsayem","description":"An Implementation of REST API server following clean architecture principles using Golang","archived":false,"fork":false,"pushed_at":"2025-03-25T21:45:58.000Z","size":3270,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T22:25:40.244Z","etag":null,"topics":["clean-architechture","docker","firestore","golang","kubernetes","redis","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hmsayem.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-12-07T13:24:46.000Z","updated_at":"2025-03-25T21:46:01.000Z","dependencies_parsed_at":"2024-01-10T17:16:02.315Z","dependency_job_id":"a24b47f9-a969-4595-a7d9-6247b04a7c80","html_url":"https://github.com/hmsayem/empora","commit_stats":null,"previous_names":["hmsayem/employee-server","hmsayem/clean-architecture-implementation","hmsayem/personnel-api","hmsayem/employee-hive","hmsayem/empora"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmsayem%2Fempora","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmsayem%2Fempora/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmsayem%2Fempora/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hmsayem%2Fempora/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hmsayem","download_url":"https://codeload.github.com/hmsayem/empora/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248799693,"owners_count":21163398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-architechture","docker","firestore","golang","kubernetes","redis","rest-api"],"created_at":"2025-04-13T23:46:09.210Z","updated_at":"2025-04-13T23:46:09.841Z","avatar_url":"https://github.com/hmsayem.png","language":"Go","readme":"### Empora\nThis is a RESTful API server implemented in Go that provides employee information of an organization. It follows the clean architecture principles which makes it testable and allows for easy integration with other frameworks, caches or databases without modifying the existing implementation. \n\nThis project utilizes mux and chi as the router, and Firestore as the database to store and retrieve employee information. Redis is also used as the cache to provide fast and efficient data retrieval. \n\n### Features:\n\nThe server supports the following CRUD operations on employee information:\n\n- Create new employee\n- Retrieve employee information by ID\n- Retrieve all employees\n- Update employee information\n- Delete employee information\n\n#### Overview:\n\u003cimg src=\"overview.jpg\" alt=\"Application Structure:\" width=\"650\"\u003e\n\n#### Control Flow:\n\u003cimg src=\"flow.jpg\" alt=\"Request Flow\" width=\"650\"\u003e\n\n### API Reference\n\n##### Get all employees\n\n```http\nGET /employees\n```\n\n##### Get an employee\n\n```http\nGET /employees/${id}\n```\n\n##### Add an employee\n\n```http\nPOST /employees\n```\n\n### Run Locally\nInstall and start Redis server for caching.\n```bash\nsudo apt install redis-server\nsudo systemctl status redis-server\n```\nClone the project.\n\n```bash\ngit clone https://github.com/hmsayem/clean-architecture-implementation.git\n```\nGo to the project directory.\n\n```bash\ncd clean-architecture-implementation\n```\n\nCopy all third-party dependencies to vendor folder.\n\n```bash\ngo mod vendor\n```\n\nExport environment variables.\n\n```bash\nGOOGLE_APPLICATION_CREDENTIALS=/path/to/project-private-key.json\n\nSERVER_PORT=:8000\n\nREDIS_SERVER_HOST=localhost:6379\n```\n\nStart the server.\n\n```bash\ngo run .\n```\n\n### Run with Docker\n#### Run Redis Server\n```bash\ndocker run --name redis --net=host -d redis\n```\n#### Run API server\nBuild image.\n\n```bash\ndocker build -t employee-server .\n```\nRun container.\n\n```bash\ndocker run --mount type=bind,source=/path/to/project-private-key.json,target=/run/secrets/project-private-key.json,readonly --env GOOGLE_APPLICATION_CREDENTIALS='/run/secrets/project-private-key.json' --env SERVER_PORT=':8000' --env REDIS_SERVER_HOST='localhost:6379' --net host employee-server\n```\n\n### Deploy on Kubernetes\nCreate secret from `project-private-key.json`\n```bash\nkubectl create secret generic firestore-secret --from-file=/path/to/project-private-key.json\n```\nCreate Configmaps\n```bash\nkubectl apply -f k8s/redis-server-cm.yaml\nkubectl apply -f k8s/employee-server-cm.yaml\n```\nCreate Pods\n```bash\nkubectl apply -f k8s/redis-server.yaml\nkubectl apply -f k8s/employee-server.yaml\n```\nCreate Services\n```bash\nkubectl apply -f k8s/redis-server-svc.yaml\nkubectl apply -f k8s/employee-server-svc.yaml\n```\nPort Forward\n```bash\nkubectl port-forward svc/employee 8000\n```\n\n### Examples of API Requests\n##### Get all employees\n```bash\n❯ curl -X GET  \"http://localhost:8000/employees\" | jq\n[\n  {\n    \"id\": 50,\n    \"name\": \"Kamol Hasan\",\n    \"title\": \"Senior Software Engineer\",\n    \"team\": \"B\",\n    \"email\": \"kamol@gmail.com\"\n  },\n  {\n    \"id\": 81,\n    \"name\": \"Piyush Kanti Das\",\n    \"title\": \"Software Engineer\",\n    \"team\": \"A\",\n    \"email\": \"piyush@gmail.com\"\n  }\n]\n```\n##### Get an employee\n```bash\n❯ curl -X GET  \"http://localhost:8000/employees/81\" | jq\n{\n  \"id\": 81,\n  \"name\": \"Piyush Kanti Das\",\n  \"title\": \"Software Engineer\",\n  \"team\": \"A\",\n  \"email\": \"piyush@gmail.com\"\n}\n```\n\n\n##### Update an employee\n```bash\n ❯ curl -X PUT \"http://localhost:8000/employees/81\" -d '{\"title\": \"Senior Software Engineer\"}'\n```\n\n##### Add an employee\n```bash\n ❯ curl -X POST \"http://localhost:8000/employees\" -d '{\"name\": \"Hossain Mahmud\",\"title\": \"Software Engineer\",\"team\": \"A\",\"email\": \"hossain@gmail.com\"}'\n\n{\"id\":89,\"name\":\"Hossain Mahmud\",\"title\":\"Software Engineer\",\"team\":\"A\",\"email\":\"hossain@gmail.com\"}\n\n```\n### Run Unit Tests\n##### Test Service Layer using Mock Repository\n```bash\ngo test service/employee-service.go  service/employee-service_test.go\n```\n### Acknowledgements\n - [Pragmatic Reviews](https://www.youtube.com/c/PragmaticReviews)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmsayem%2Fempora","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhmsayem%2Fempora","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhmsayem%2Fempora/lists"}