00f5d0c4ba
Compliance portal already embeds and serves the public SPA, so the old @probo/trust app was unused. Drop its Makefile/CI stubs, Relay project, CORS port, and the helper that only it imported. Signed-off-by: Émile Ré <emile@probo.com>
98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
# File naming conventions
|
|
|
|
## Template files
|
|
|
|
Template files use the extension pattern `<name>.<output-ext>.tmpl`:
|
|
|
|
```
|
|
pkg/complianceportal/visitor/sitemap.xml.tmpl
|
|
pkg/server/mailactions/templates/page.html.tmpl
|
|
pkg/cookiebanner/prompts/tracker_identification.txt.tmpl
|
|
pkg/probo/templates/risk_list.json.tmpl
|
|
compose/keycloak/probo-realm.json.tmpl
|
|
pkg/esign/certificate.html.tmpl
|
|
```
|
|
|
|
The `<output-ext>` indicates the format produced after rendering (`.xml`, `.html`, `.txt`, `.json`). The final `.tmpl` suffix marks the file as a template requiring substitution before use.
|
|
|
|
### Dynamic values over hardcoded lists
|
|
|
|
Never hardcode enum values or source-of-truth lists in template text. Use a
|
|
placeholder and substitute at runtime so the template stays in sync with the
|
|
code:
|
|
|
|
```
|
|
Use one of: {{.Categories}}.
|
|
```
|
|
|
|
For single-placeholder templates, `strings.Replace` is sufficient. For multiple
|
|
placeholders, use `text/template`.
|
|
|
|
## Worker files
|
|
|
|
Background worker files use the `<name>_worker.go` naming pattern. The file
|
|
contains the handler struct, `NewXxxWorker` constructor, and the `Claim`/`Process`
|
|
methods. Keep domain-specific helper methods (match, resolve, etc.) in the same
|
|
file.
|
|
|
|
```
|
|
pkg/cookiebanner/tracker_mapping_worker.go
|
|
pkg/cookiebanner/pattern_analysis_worker.go
|
|
```
|
|
|
|
## Agent files
|
|
|
|
A file whose **sole purpose** is to construct and operate an agent uses the
|
|
`<name>_agent.go` suffix. The agent file owns agent construction, prompt
|
|
building, the `//go:embed` directive for prompt templates, the typed result,
|
|
the agent-specific config, and any agent-only constants (timeout, confidence
|
|
threshold). Callers (workers, services) hold a `*agent.Agent` field and import
|
|
the file's `Build…Agent` constructor.
|
|
|
|
This applies in two shapes:
|
|
|
|
1. **Paired with a worker** (most common). The worker file
|
|
`<worker_prefix>_worker.go` stays focused on `Claim`/`Process`, and the
|
|
agent it uses lives in `<worker_prefix>_agent.go` next to it.
|
|
|
|
```
|
|
pkg/cookiebanner/tracker_mapping_worker.go -- worker handler
|
|
pkg/cookiebanner/tracker_mapping_agent.go -- agent construction + prompts
|
|
```
|
|
|
|
2. **Standalone, called from elsewhere.** When the agent is consumed by a
|
|
different package (or by multiple packages — e.g. an agent that operates on
|
|
a domain entity, used by several feature workers), it lives in the package
|
|
that owns the domain, named `<purpose>_agent.go`.
|
|
|
|
```
|
|
pkg/thirdparty/disambiguation_agent.go -- catalog→org ThirdParty matcher
|
|
pkg/vetting/sub_agent.go -- generic vetting sub-agent
|
|
```
|
|
|
|
A file is NOT renamed to `_agent.go` when the agent is incidental to a service
|
|
that does substantially more than agent orchestration (e.g. CRUD, caching,
|
|
auth). In that case the file keeps its service name and the agent is built
|
|
inline:
|
|
|
|
```
|
|
pkg/evidencedescriber/evidencedescriber.go -- single-file describer service
|
|
pkg/vetting/assessment.go -- third-party assessment service
|
|
```
|
|
|
|
If the agent construction grows past a few dozen lines or sprouts its own
|
|
prompt embed / typed result / config struct, extract it into a sibling
|
|
`<purpose>_agent.go`.
|
|
|
|
## Tool files
|
|
|
|
Each agent tool lives in its own `<tool_name>_tool.go` file, named after the
|
|
tool constructor function (without the `Tool` suffix). The file contains the
|
|
constructor function plus its param/result types. Avoid grouping multiple tools
|
|
in a single file.
|
|
|
|
```
|
|
pkg/cookiebanner/search_tracker_patterns_tool.go -- searchTrackerPatternsTool
|
|
pkg/cookiebanner/search_third_parties_tool.go -- searchThirdPartiesTool
|
|
```
|