|
| 1 | +# AGENTS Guidelines for This Repository |
| 2 | + |
| 3 | +This repository is a Go project following the **microservice** architecture design. Services including: |
| 4 | + |
| 5 | +- **API**: The API service handles HTTP requests and responses. It is the entry point for external clients to interact with the system. |
| 6 | +- **User**: The User service handles user-related operations, such as user registration, login, and profile management. All requests are proxied to this service from the API service. |
| 7 | +- **Accounting**: The Accounting service handles accounting-related operations, such as recording user token or hardware resource usage, or updating user balances. All requests are proxied to this service from the API service. |
| 8 | +- **Moderation**: The Moderation service handles content moderation operations, such as flagging inappropriate text or images. All requests are proxied to this service from the API service. |
| 9 | +- **DataViewer**: The DataViewer service handles dataset preview operations, such as fetching dataset metadata or previewing dataset files. All requests are proxied to this service from the API service. |
| 10 | +- **Notification**: The Notification service handles sending notifications to users, such as email or push notifications. All requests are proxied to this service from the API service. |
| 11 | +- **Payment**: The Payment service handles payment operations, such as processing payments or refunding payments. All requests are proxied to this service from the API service. |
| 12 | +- **AIGateway**: The AIGateway service handles AI model inference operations, such as running AI models or generating AI outputs. It's another entry point for external clients to interact with the AI models. |
| 13 | +- **Runner**: The Runner service is a bridge between api service and Kubernetes cluster. It handles deployment of models, spaces. |
| 14 | +- **LogCollector**: The LogCollector service handles collecting logs from Kubernetes cluster. All logs are sent to this service from the Runner service and API service. |
| 15 | + |
| 16 | +# Structure |
| 17 | +Every service follows the layered architecture design: handler -> component -> builder (database, rpc, git, etc.). |
| 18 | + |
| 19 | +- The handler layer handles HTTP requests and responses. |
| 20 | +- The component layer handles business logic and coordinates between different layers. |
| 21 | +- The builder layer handles low-level operations, such as database access, RPC calls, or Git operations. |
| 22 | +- Every golang file should have a corresponding `*_test.go` file for unit tests. |
| 23 | + |
| 24 | +Folders relative to the root of the repository for each service: |
| 25 | + |
| 26 | +| Service | Folder | |
| 27 | +|---------|--------| |
| 28 | +| API | api | |
| 29 | +| User | user | |
| 30 | +| Accounting | accounting | |
| 31 | +| Moderation | moderation | |
| 32 | +| DataViewer | dataviewer | |
| 33 | +| Notification | notification | |
| 34 | +| Payment | payment | |
| 35 | +| AIGateway | aigateway | |
| 36 | +| Runner | runner | |
| 37 | +| LogCollector | logcollector | |
| 38 | + |
| 39 | +## Examples |
| 40 | + |
| 41 | +### Router |
| 42 | + |
| 43 | +- `api/router/api.go` is an example of a router that registers HTTP routes and their corresponding handlers for common functionality across services. |
| 44 | +- `accounting/router/api.go` is an example of a router that registers HTTP routes and their corresponding handlers for the Accounting service. |
| 45 | +- `runner/router/api.go` is an example of a router that registers HTTP routes and their corresponding handlers for the runner service. |
| 46 | + |
| 47 | +### Handler Layer |
| 48 | + |
| 49 | +- `api/handler/space.go` is an example of a handler that deals with space-related HTTP requests. |
| 50 | +- `api/handler/evaluation.go` is an example of a handler that deals with evaluation-related HTTP requests. |
| 51 | + |
| 52 | +### Component Layer |
| 53 | + |
| 54 | +- `component/space.go` is an example of a component that deals with space-related business logic. |
| 55 | +- `component/evaluation.go` is an example of a component that deals with evaluation-related business logic. |
| 56 | + |
| 57 | +### Database Builder Layer |
| 58 | + |
| 59 | +- `builder/store/database/space.go` is an example of a builder that deals with space-related database operations. |
| 60 | + |
| 61 | +### Database Migration |
| 62 | + |
| 63 | +- `builder/store/database/migrations/20240201061926_create_spaces.go` is an example of a database migration script that creates a space table. |
| 64 | +- use `go run cmd/csghub-server/main.go migration create_go` to generate a go database migration script. |
| 65 | +- use `go run cmd/csghub-server/main.go migration create_sql` to generate a sql database migration script. |
| 66 | + |
| 67 | +### Space Deploy |
| 68 | + |
| 69 | +- `builder/deploy/deployer.go` create build and deploy task in database, then create temporal workflow to run the task. |
| 70 | +- `api/workflow/activity/deploy_activity.go` impletements temporal activities to run the build and deploy task by call runner api. |
| 71 | +- `runner/handler/imagebuilder.go` implements runner api to trigger image builder process by call image builder component. |
| 72 | +- `runner/component/imagebuilder.go` implements runner component to trigger deploy process by call knative api. |
| 73 | +- `runner/handler/service.go` implements runner api to trigger deploy process by call deploy component. |
| 74 | +- `runner/component/service.go` implements runner component to trigger deploy process by call knative api. |
| 75 | +- `docker/spaces/builder/Dockerfile*` are Dockerfile that builds the space image. |
| 76 | + |
| 77 | +## Code Style & Conventions: |
| 78 | + |
| 79 | +- Each layer's interface should only expose data structures defined within its own layer or common type definitions from the common.types package. For example, interfaces in the Component layer (such as UserComponent) should not return data structures from the underlying database layer (such as database.User structure), as the database layer is considered lower-level than the component layer. |
| 80 | +- Write unit tests for new code. |
| 81 | +- Use struct data types instead of primitive types for function parameters and return values. |
| 82 | +- All variables should be named in camelCase. |
| 83 | +- Variables should be declared at the smallest possible scope under `common/types`. |
| 84 | + |
| 85 | +### Do |
| 86 | + |
| 87 | +### Do Not |
| 88 | + |
| 89 | +## Testing |
| 90 | + |
| 91 | +- Use `make mock_gen GO_TAGS={go.buildTags}` to generate mock implementations for the interfaces. |
| 92 | +- Use `make test GO_TAGS={go.buildTags}` to run all tests in project. |
| 93 | +- Mock dependencies (e.g., database, RPC clients) using tools like `mockery`. |
| 94 | + |
| 95 | +## Tools |
| 96 | + |
| 97 | +- Search `Makefile` for running, building, testing, and linting tools. |
| 98 | +- Swagger doc is generated by `swag` tool, and it will be served by handler layer. |
| 99 | + |
| 100 | +## Commit & Pull Request Guidelines: |
| 101 | + |
| 102 | +- Each PR must include a clear description of the changes made and their impact, including root cause analysis if applicable, and solution details, and local test result. |
| 103 | + |
| 104 | +## Specific Instructions |
0 commit comments