[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F571SV5F73EYCSZ1MSK0CE":3,"skill-same:01M7F571SV5F73EYCSZ1MSK0CE":43},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":28,"install":29,"resources":42},"01M7F571SV5F73EYCSZ1MSK0CE","architecture",null,"How a backend service is laid out and started: its directories, its main(), the App container, graceful shutdown, where shared code lives, how to run the stack locally, and how to add a new service.","workflowaiorg\u002Fworkflow","workflowaiorg","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F344728430?v=4","01M7F5606QN4BXN2KJNCJPCKAZ","01M7F5607RE7Y5NNRN60FW9NJ3",0,"MIT","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Fcomponent\u002Fbackend\u002Fbase\u002Fskills\u002Farchitecture\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: architecture\ndescription: \"How a backend service is laid out and started: its directories, its main(), the App container, graceful shutdown, where shared code lives, how to run the stack locally, and how to add a new service.\"\n---\n\n# Skill: Service architecture\n\nEvery service is built the same way, so anyone who knows one knows them all.\n\n## When this skill applies\n\n- Adding a new service\n- Changing a `cmd\u002F` entrypoint, `internal\u002Fapp\u002F`, startup or shutdown\n- Deciding whether code belongs to one service or to `pkg\u002F`\n- Starting, stopping or checking the app locally\n\n## A service's layout\n\n```text\n\u003Cservice>\u002F\n├── cmd\u002Fhttp\u002Fmain.go          # the entrypoint; cmd\u002Fgrpc\u002F for a gRPC service\n├── cmd\u002Fopenapi\u002Fmain.go       # writes openapi.yaml from the routes' operations\n├── openapi.yaml              # the HTTP contract, generated: see the api-design skill\n└── internal\u002F\n    ├── app\u002Fapp.go            # App: settings and connections opened once, shared by the routes\n    ├── config\u002Fconfig.go      # Config and Load(): see the configuration skill\n    ├── controller\u002F\u003Cdomain>\u002F  # business logic; defines the interfaces it needs\n    ├── gateway\u002F\u003Cdomain>\u002F\u003Ctransport>\u002F     # calls to other services: http\u002F, grpc\u002F\n    ├── repository\u002F\u003Cdomain>\u002F\u003Cdriver>\u002F     # the database: postgres\u002F\n    ├── handler\u002F\u003Cdomain>\u002F\u003Ctransport>\u002F     # requests in: http\u002F, grpc\u002F\n    ├── model\u002F                # the domain's structs, shared by the layers\n    └── route\u002F\u003Cdomain>.go     # wiring: gateway\u002Frepository → controller → handler → routes\n```\n\nA transport is always a directory of its own: HTTP and gRPC code never share a package. The api-design\nskill says what each layer may do.\n\n## main()\n\nThe order never changes:\n\n1. `logging.Init()`.\n2. `cfg := config.Load()`, then check every required setting and `os.Exit(1)` with a message naming\n   the variable when one is missing.\n3. `app.New(cfg)`: open what is opened once, such as a database pool;\n   `main` closes it once the server has stopped.\n4. `ctx` from `signal.NotifyContext`, which ends on SIGINT or SIGTERM.\n5. `gin.New()` (never `gin.Default()`), with `gin.Recovery()` and `middleware.CorrelationID()`, and\n   `SetTrustedProxies` set explicitly.\n6. `route.Register(ctx, application, r)`, which registers each domain's routes; an error is logged\n   and exits 1.\n7. Serve until `ctx` ends, then shut down with a timeout, so requests in flight finish.\n\n`api\u002Fcmd\u002Fhttp\u002Fmain.go` is the reference: copy it.\n\n**A service no client calls directly** serves only the routes other services call, under\n`\u002Finternal\u002F\u003Cservice>\u002F`, so one rule at the edge can keep them all private. Authentication happens\nonce, in the service that faces clients; services behind it trust its calls and do not check again.\n\n## The App container\n\n`internal\u002Fapp.App` holds the settings and what is opened once. Routes receive `*app.App`; it is a\nstruct, never an interface. A helper every handler needs, such as the signed-in user, is a method\non it.\n\n## Where code goes\n\n| Where | For |\n|---|---|\n| `pkg\u002F` at the root | code more than one service uses: logging, errors, HTTP helpers, middleware |\n| `\u003Cservice>\u002Fpkg\u002F` | code shared inside one service only |\n\nMove code to the root `pkg\u002F` only when a second service needs it, and then move it rather than\ncopy it.\n\n## Running it\n\nThe local stack is `docker-compose.yaml` at the project's root; run compose there.\n\n- Start: `docker compose up -d`. The first start compiles for a minute.\n- Check: `curl -sf --retry 30 --retry-all-errors http:\u002F\u002Flocalhost:8000\u002Fhealth` answers once `api`\n  has compiled; each service has its own host port.\n- Logs: `docker compose logs \u003Cservice>`; add `-f` only in a terminal a person watches, since it\n  never returns.\n- Stop: `docker compose down`.\n\n## A new service\n\n1. Copy `api\u002F` to `\u003Cservice>\u002F` and replace `api` in its import paths.\n2. Keep `internal\u002Fconfig`, `internal\u002Fapp`, the health route, `cmd\u002Fhttp\u002Fmain.go` and\n   `cmd\u002Fopenapi\u002Fmain.go`; remove the domains it does not have, from `route.Register` and\n   `route.Operations()` too, and regenerate its `openapi.yaml` with `go run .\u002F\u003Cservice>\u002Fcmd\u002Fopenapi`.\n3. Add it to `docker-compose.yaml`, as `api` is, with a host port of its own.\n4. `go vet .\u002F... && go test .\u002F...`, then `docker compose up -d`, and check that its `\u002Fhealth`\n   answers on its port, as *Running it* says.\n\n## Definition of done\n\n- [ ] The layout matches the tree above, with each transport in a directory of its own\n- [ ] `main()` keeps the order under *main()*, failing fast on a missing setting\n- [ ] Shared state hangs off `App`, not package variables\n- [ ] Shutdown is graceful\n- [ ] Code shared by services is in the root `pkg\u002F`, and only there\n","# Skill: Service architecture\n\nEvery service is built the same way, so anyone who knows one knows them all.\n\n## When this skill applies\n\n- Adding a new service\n- Changing a `cmd\u002F` entrypoint, `internal\u002Fapp\u002F`, startup or shutdown\n- Deciding whether code belongs to one service or to `pkg\u002F`\n- Starting, stopping or checking the app locally\n\n## A service's layout\n\n```text\n\u003Cservice>\u002F\n├── cmd\u002Fhttp\u002Fmain.go          # the entrypoint; cmd\u002Fgrpc\u002F for a gRPC service\n├── cmd\u002Fopenapi\u002Fmain.go       # writes openapi.yaml from the routes' operations\n├── openapi.yaml              # the HTTP contract, generated: see the api-design skill\n└── internal\u002F\n    ├── app\u002Fapp.go            # App: settings and connections opened once, shared by the routes\n    ├── config\u002Fconfig.go      # Config and Load(): see the configuration skill\n    ├── controller\u002F\u003Cdomain>\u002F  # business logic; defines the interfaces it needs\n    ├── gateway\u002F\u003Cdomain>\u002F\u003Ctransport>\u002F     # calls to other services: http\u002F, grpc\u002F\n    ├── repository\u002F\u003Cdomain>\u002F\u003Cdriver>\u002F     # the database: postgres\u002F\n    ├── handler\u002F\u003Cdomain>\u002F\u003Ctransport>\u002F     # requests in: http\u002F, grpc\u002F\n    ├── model\u002F                # the domain's structs, shared by the layers\n    └── route\u002F\u003Cdomain>.go     # wiring: gateway\u002Frepository → controller → handler → routes\n```\n\nA transport is always a directory of its own: HTTP and gRPC code never share a package. The api-design\nskill says what each layer may do.\n\n## main()\n\nThe order never changes:\n\n1. `logging.Init()`.\n2. `cfg := config.Load()`, then check every required setting and `os.Exit(1)` with a message naming\n   the variable when one is missing.\n3. `app.New(cfg)`: open what is opened once, such as a database pool;\n   `main` closes it once the server has stopped.\n4. `ctx` from `signal.NotifyContext`, which ends on SIGINT or SIGTERM.\n5. `gin.New()` (never `gin.Default()`), with `gin.Recovery()` and `middleware.CorrelationID()`, and\n   `SetTrustedProxies` set explicitly.\n6. `route.Register(ctx, application, r)`, which registers each domain's routes; an error is logged\n   and exits 1.\n7. Serve until `ctx` ends, then shut down with a timeout, so requests in flight finish.\n\n`api\u002Fcmd\u002Fhttp\u002Fmain.go` is the reference: copy it.\n\n**A service no client calls directly** serves only the routes other services call, under\n`\u002Finternal\u002F\u003Cservice>\u002F`, so one rule at the edge can keep them all private. Authentication happens\nonce, in the service that faces clients; services behind it trust its calls and do not check again.\n\n## The App container\n\n`internal\u002Fapp.App` holds the settings and what is opened once. Routes receive `*app.App`; it is a\nstruct, never an interface. A helper every handler needs, such as the signed-in user, is a method\non it.\n\n## Where code goes\n\n| Where | For |\n|---|---|\n| `pkg\u002F` at the root | code more than one service uses: logging, errors, HTTP helpers, middleware |\n| `\u003Cservice>\u002Fpkg\u002F` | code shared inside one service only |\n\nMove code to the root `pkg\u002F` only when a second service needs it, and then move it rather than\ncopy it.\n\n## Running it\n\nThe local stack is `docker-compose.yaml` at the project's root; run compose there.\n\n- Start: `docker compose up -d`. The first start compiles for a minute.\n- Check: `curl -sf --retry 30 --retry-all-errors http:\u002F\u002Flocalhost:8000\u002Fhealth` answers once `api`\n  has compiled; each service has its own host port.\n- Logs: `docker compose logs \u003Cservice>`; add `-f` only in a terminal a person watches, since it\n  never returns.\n- Stop: `docker compose down`.\n\n## A new service\n\n1. Copy `api\u002F` to `\u003Cservice>\u002F` and replace `api` in its import paths.\n2. Keep `internal\u002Fconfig`, `internal\u002Fapp`, the health route, `cmd\u002Fhttp\u002Fmain.go` and\n   `cmd\u002Fopenapi\u002Fmain.go`; remove the domains it does not have, from `route.Register` and\n   `route.Operations()` too, and regenerate its `openapi.yaml` with `go run .\u002F\u003Cservice>\u002Fcmd\u002Fopenapi`.\n3. Add it to `docker-compose.yaml`, as `api` is, with a host port of its own.\n4. `go vet .\u002F... && go test .\u002F...`, then `docker compose up -d`, and check that its `\u002Fhealth`\n   answers on its port, as *Running it* says.\n\n## Definition of done\n\n- [ ] The layout matches the tree above, with each transport in a directory of its own\n- [ ] `main()` keeps the order under *main()*, failing fast on a missing setting\n- [ ] Shared state hangs off `App`, not package variables\n- [ ] Shutdown is graceful\n- [ ] Code shared by services is in the root `pkg\u002F`, and only there\n",{"name":5,"description":7},"main","68fb57dd74de5ed76dcfaff357932684f77650e6","internal\u002Fcomponent\u002Fbackend\u002Fbase\u002Fskills\u002Farchitecture","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg","2026-11-13 17:41:05",{"source":8,"skillName":5,"commands":30,"prompt":40,"zipAvailable":41},[31,34,37],{"tool":32,"command":33},"npx","npx skills add workflowaiorg\u002Fworkflow --skill architecture",{"tool":35,"command":36},"bunx","bunx skills add workflowaiorg\u002Fworkflow --skill architecture",{"tool":38,"command":39},"pnpm","pnpm dlx skills add workflowaiorg\u002Fworkflow --skill architecture","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Fcomponent\u002Fbackend\u002Fbase\u002Fskills\u002Farchitecture\u002FSKILL.md",true,[],[44,51,58,65,72,77],{"skillNo":45,"name":46,"nameZh":6,"description":47,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":48,"categories":49,"keywords":50,"publishedAt":18},"01M7F58YP2QA8F89599TDWEY0Y","notes","Where notes go.","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.opencode\u002Fskills\u002Fnotes\u002FSKILL.md",[],[],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":18},"01M7F58X62078DBFA7YZH0M9VP","naming","How things are named, including the sample's tables.","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.opencode\u002Fskills\u002Fnaming\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":18},"01M7F58VXX28G09AJCA667GHBS","local","A skill only this project has.","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.opencode\u002Fskills\u002Flocal\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":18},"01M7F58TQ8XVBD6SDV0S4T6E77","hello","Greets sample's developers.","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.opencode\u002Fskills\u002Fhello\u002FSKILL.md",[],[],{"skillNo":73,"name":46,"nameZh":6,"description":47,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":74,"categories":75,"keywords":76,"publishedAt":18},"01M7F58R379TW8C6VY572RK11F","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.github\u002Fskills\u002Fnotes\u002FSKILL.md",[],[],{"skillNo":78,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":18},"01M7F58PNRREJ4KPY496M2XHSY","https:\u002F\u002Fgithub.com\u002Fworkflowaiorg\u002Fworkflow\u002Fblob\u002Fmain\u002Finternal\u002Frender\u002Ftestdata\u002Fsync\u002Fwant\u002F.github\u002Fskills\u002Fnaming\u002FSKILL.md",[],[]]