The Go backend for Fieldforce uses hexagonal clean architecture (Ports & Adapters + DDD), mirroring the pattern established by the leave module. It exposes RESTful HTTP endpoints for managing tasks, activities, and accessing audit logs.
Task status transitions are enforced using a pure-function generic state machine residing in the shared kernel (internal/shared/domain/statemachine).
The PATCH API uses event-based transitions (e.g., { "event": "approve" }) rather than target statuses to ensure the state machine executes all guard logic natively at the server. See ADR-0013.
Audit Logs: All state transitions and task actions generate audit events written to the shared audit_log table with entity_type = 'FIELDFORCE_TASK'.
Append-Only Notes: Rejection feedback from managers is securely stored as an append-only JSONB array (review_notes) in ff_tasks (ADR-0015) to maintain explicit, immutable context across multiple review cycles.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Monorepo","colors":{"primary":"#16A34A","light":"#07C983","dark":"#15803D"},"favicon":"/favicon.svg","integrations":{"telemetry":{"enabled":false}},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"hasAudioNarration":false,"customDomains":[],"gitSource":{"type":"github","owner":"local","repo":"local","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":"local","isBase":true},"buildId":"local","clientVersion":"0.0.4044"},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[],"googleFontsInlined":false,"isLoggedInCli":false,"mintExport":{}},"customCss":[],"page":{"pagePath":"backend/go/modules/fieldforce","slug":"/backend/go/modules/fieldforce","pageMetadata":{"title":"Fieldforce Module","description":"Backend implementation details for the Fieldforce module in Go.","href":"/backend/go/modules/fieldforce"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Backend implementation details for the Fieldforce module in Go.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={code:`code`,li:`li`,ol:`ol`,p:`p`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{Heading,Tip}=_components;if(!Heading)_missingMdxReference(`Heading`,true);if(!Tip)_missingMdxReference(`Tip`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`1`,id:`fieldforce-backend-implementation`,children:`Fieldforce Backend Implementation`}),`\n`,_jsx(Heading,{level:`2`,id:`overview`,children:`Overview`}),`\n`,_jsxs(_components.p,{children:[`The Go backend for Fieldforce uses hexagonal clean architecture (Ports \u0026 Adapters + DDD), mirroring the pattern established by the `,_jsx(_components.code,{children:`leave`}),` module. It exposes RESTful HTTP endpoints for managing tasks, activities, and accessing audit logs.`]}),`\n`,_jsx(Heading,{level:`2`,id:`layered-structure`,children:`Layered Structure`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Domain Entities`}),`: `,_jsx(_components.code,{children:`Task`}),`, `,_jsx(_components.code,{children:`Activity`}),`, `,_jsx(_components.code,{children:`TaskStatus`}),`, `,_jsx(_components.code,{children:`TaskPriority`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Application Ports`}),`: Defines interfaces for Repositories (`,_jsx(_components.code,{children:`TaskRepository`}),`, `,_jsx(_components.code,{children:`ActivityRepository`}),`, `,_jsx(_components.code,{children:`AuditLogRepository`}),`) and Services (`,_jsx(_components.code,{children:`TaskService`}),`, `,_jsx(_components.code,{children:`ActivityService`}),`).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Use Cases`}),`: Core business logic in `,_jsx(_components.code,{children:`TaskService`}),`, wrapped by `,_jsx(_components.code,{children:`AuditedTaskService`}),` for automatic audit logging using a decorator pattern.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Persistence Adapter`}),`: PostgreSQL implementations mapped to DB row structs, handling junction tables seamlessly.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`HTTP Adapter`}),`: Echo handlers under `,_jsx(_components.code,{children:`internal/modules/fieldforce/adapter/inbound/http/`}),`.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`state-machine`,children:`State Machine`}),`\n`,_jsxs(_components.p,{children:[`Task status transitions are enforced using a pure-function generic state machine residing in the shared kernel (`,_jsx(_components.code,{children:`internal/shared/domain/statemachine`}),`).`]}),`\n`,_jsx(Tip,{children:_jsxs(_components.p,{children:[`The PATCH API uses event-based transitions (e.g., `,_jsx(_components.code,{children:`{ \"event\": \"approve\" }`}),`) rather than target statuses to ensure the state machine executes all guard logic natively at the server. See ADR-0013.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`pagination`,children:`Pagination`}),`\n`,_jsxs(_components.p,{children:[`The backend API exposes an endpoint that supports dual pagination modes via the `,_jsx(_components.code,{children:`X-Pagination-Type`}),` header:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Offset Pagination`}),`: Commonly used by the Desktop Panel (SolidStart) via `,_jsx(_components.code,{children:`page`}),` and `,_jsx(_components.code,{children:`page_size`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Cursor Pagination`}),`: Used by the Mobile Web app (Astro) for stable infinite scrolling over tasks without skips.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`feature-flags-adr-0016`,children:`Feature Flags (ADR-0016)`}),`\n`,_jsx(_components.p,{children:`Two-tier feature flag middleware gates access to the Fieldforce module:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`Global `,_jsx(_components.code,{children:`admin_feature_flags`}),` (platform-wide kill switch).`]}),`\n`,_jsxs(_components.li,{children:[`Per-org `,_jsx(_components.code,{children:`org_feature_flags`}),` (tenant-specific toggle).`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`Effective access requires both layers to be enabled. Missing rows are defensively treated as enabled.`}),`\n`,_jsx(Heading,{level:`2`,id:`auditing-and-feedback-loop`,children:`Auditing and Feedback Loop`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Audit Logs`}),`: All state transitions and task actions generate audit events written to the shared `,_jsx(_components.code,{children:`audit_log`}),` table with `,_jsx(_components.code,{children:`entity_type = 'FIELDFORCE_TASK'`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Append-Only Notes`}),`: Rejection feedback from managers is securely stored as an append-only JSONB array (`,_jsx(_components.code,{children:`review_notes`}),`) in `,_jsx(_components.code,{children:`ff_tasks`}),` (ADR-0015) to maintain explicit, immutable context across multiple review cycles.`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Fieldforce Module","description":"Backend implementation details for the Fieldforce module in Go.","href":"/backend/go/modules/fieldforce"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Fieldforce Backend Implementation","slug":"fieldforce-backend-implementation","depth":1,"children":[]},{"title":"Overview","slug":"overview","depth":2,"children":[]},{"title":"Layered Structure","slug":"layered-structure","depth":2,"children":[]},{"title":"State Machine","slug":"state-machine","depth":2,"children":[]},{"title":"Pagination","slug":"pagination","depth":2,"children":[]},{"title":"Feature Flags (ADR-0016)","slug":"feature-flags-adr-0016","depth":2,"children":[]},{"title":"Auditing and Feedback Loop","slug":"auditing-and-feedback-loop","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"localhost","siteName":"Monorepo","title":"Fieldforce Module - Monorepo","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"originalFileLocation":"backend/go/modules/fieldforce.md"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Backend implementation details for the Fieldforce module in Go.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Monorepo\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/favicons/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/favicons/favicon-32x32.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/favicons/favicon-16x16.png\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/favicons/favicon.ico\">\u003cmeta data-mint-head property=\"og:title\" content=\"Fieldforce Module - Monorepo\">\u003cmeta data-mint-head property=\"og:description\" content=\"Backend implementation details for the Fieldforce module in Go.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Monorepo\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://local./backend/go/modules/fieldforce\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Fieldforce Module - Monorepo\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Backend implementation details for the Fieldforce module in Go.\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/favicons/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Monorepo\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#16A34A\">\u003clink data-mint-head rel=\"canonical\" href=\"https://local./backend/go/modules/fieldforce\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/backend/go/modules/fieldforce.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Monorepo\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Monorepo","nav":{"tabs":[{"tab":"ADRs","pages":[{"title":"ADRs","href":"/adr"}]},{"tab":"Backend","pages":[{"title":"Backend","href":"/backend/hexagonal-architecture-guide"}]},{"tab":"Backend (Go)","groups":[{"group":"Documentations","pages":[{"title":"Go Backend Overview","href":"/backend/go"},{"title":"Backend (Go) Documentation","href":"/backend/go/backend-go-doc"},{"title":"Documentation Structure","href":"/backend/go/structure"}]},{"group":"Getting Started","pages":[{"title":"01 - [ Getting Started Index ]","href":"/backend/go/getting-started/index"},{"title":"Backend Getting Started","href":"/backend/go/getting-started/backend-getting-started"},{"title":"Better Auth Integration","href":"/backend/go/getting-started/better-auth-integration"},{"title":"Backend Setup","href":"/backend/go/getting-started/setup"},{"title":"Backend Architecture Roadmap","href":"/backend/go/getting-started/roadmap"}]},{"group":"Architecture","pages":[{"title":"02 - [ Architecture Index ]","href":"/backend/go/architecture/index"},{"title":"Architecture \u0026 Design Decisions","href":"/backend/go/architecture/architecture"},{"title":"CQRS Implementation Guide","href":"/backend/go/architecture/cqrs"},{"title":"CQRS Implementation for Leave Management Module","href":"/backend/go/architecture/cqrs-leave-management"},{"title":"Backend Architecture: Handler Organization","href":"/backend/go/architecture/handler-organization"},{"title":"Microservice Decoupling Pattern","href":"/backend/go/architecture/microservice-decoupling-pattern"},{"title":"Authentication Architecture","href":"/backend/go/architecture/authentication"},{"title":"Better Auth Plugin Integration","href":"/backend/go/architecture/auth-plugin-integration"},{"title":"Transactional Outbox Pattern Implementation","href":"/backend/go/architecture/outbox-pattern"},{"title":"Backend Architecture: Shared Infrastructure (Ports \u0026 Adapters)","href":"/backend/go/architecture/shared-infrastructure"}]},{"group":"API","pages":[{"title":"03 - [ Api Index ]","href":"/backend/go/api/index"},{"title":"GraphQL Development Workflow","href":"/backend/go/api/graphql-workflow"},{"title":"What gqlgen Generates - Complete Guide","href":"/backend/go/api/gqlgen-generated-code"},{"title":"Leave Types API Documentation","href":"/backend/go/api/leave-types-api"},{"title":"Pagination API","href":"/backend/go/api/pagination"},{"title":"REST + GraphQL Coexistence Example","href":"/backend/go/api/rest-graphql-example"}]},{"group":"Modules","pages":[{"title":"04 - [ Modules Index ]","href":"/backend/go/modules/index"},{"title":"Authentication Module Functional Specifications","href":"/backend/go/modules/auth"},{"title":"User Module Functional Specifications","href":"/backend/go/modules/user"},{"title":"Organization Module","href":"/backend/go/modules/organization"},{"title":"Leave Management Module","description":"Functional specification and approval workflow for leave requests","href":"/backend/go/modules/leave"},{"title":"Fieldforce Module","href":"/backend/go/modules/fieldforce"},{"title":"Digital Worker Module","description":"Backend map of the Digital Worker (Team Chat Observer) module in Go — phases, architecture, data model, flags, semantic history search, and planned media support.","href":"/backend/go/modules/digital-worker"},{"title":"AI Access Module","href":"/backend/go/modules/ai"}]},{"group":"Infrastructure","pages":[{"title":"05 - [ Infrastructure Index ]","href":"/backend/go/infrastructure/index"},{"title":"ClawUI Deployment Guide","href":"/backend/go/infrastructure/deployment"},{"title":"Deployment Quick Reference","href":"/backend/go/infrastructure/deployment-quick-ref"},{"title":"Go Backend Deployment Workflow","href":"/backend/go/infrastructure/deployment-workflow"},{"title":"ArgoCD Deployment Guide","href":"/backend/go/infrastructure/argocd-deployment"},{"title":"Multi-Environment Setup","href":"/backend/go/infrastructure/multi-environment-setup"},{"title":"Database Migrations","href":"/backend/go/infrastructure/migrations"},{"title":"OpenTelemetry \u0026 Distributed Tracing","href":"/backend/go/infrastructure/opentelemetry"},{"title":"Outbox Pattern - Quick Reference","href":"/backend/go/infrastructure/outbox-quick-ref"},{"title":"Rate Limiting \u0026 Security","href":"/backend/go/infrastructure/rate-limiting"}]},{"group":"Development","pages":[{"title":"06 - [ Development Index ]","href":"/backend/go/development/index"},{"title":"Backend Coding Conventions","href":"/backend/go/development/coding"},{"title":"Data Validation in Go - The Zod Equivalent","href":"/backend/go/development/validation"},{"title":"Automatic Validation Middleware","href":"/backend/go/development/validation-middleware"},{"title":"Query-Only Repository Implementation Guide (Better Auth)","href":"/backend/go/development/repository-implementations"},{"title":"Audit Trail vs Audit Log","href":"/backend/go/development/audit-trail-vs-audit-log"},{"title":"Automatic Audit Logging Implementation","href":"/backend/go/development/automatic-audit-logging"},{"title":"Audit Logging Integration Guide","href":"/backend/go/development/audit-logging-integration"},{"title":"Context Extraction \u0026 Audit Middleware Implementation","href":"/backend/go/development/context-extraction-implementation"},{"title":"User Name Lookup Implementation","href":"/backend/go/development/user-name-lookup-implementation"}]},{"group":"Guides","pages":[{"title":"07 Guides","href":"/backend/go/guides/index"},{"title":"Quick Start - Better Auth \u0026 NATS Sync","href":"/backend/go/guides/quickstart"},{"title":"Mobile App Authentication with JWT","href":"/backend/go/guides/mobile-auth"},{"title":"Module Configuration Guide","href":"/backend/go/guides/module-configuration"},{"title":"Event-Driven Integration - Testing Guide","href":"/backend/go/guides/webhook-testing"},{"title":"Partner API Webhooks","href":"/backend/go/guides/partner-api-webhooks"},{"title":"Morning Routine Ingest - Agent Guide","href":"/backend/go/guides/morning-routine-ingest"},{"title":"Role Assignment and Authorization","href":"/backend/go/guides/role-assignment"},{"title":"Permission Service Integration","href":"/backend/go/guides/permission-service-integration"},{"title":"Linting with golangci-lint","href":"/backend/go/guides/linting"},{"title":"Troubleshooting Guide","href":"/backend/go/guides/troubleshooting"}]}]},{"tab":"Backend (Bun)","pages":[{"title":"Backend (Bun)","href":"/backend/bun"}]},{"tab":"Frontend (SolidStart)","pages":[{"title":"Frontend (SolidStart)","href":"/frontend/solidstart"}]},{"tab":"Frontend (Astro)","pages":[{"title":"Frontend (Astro)","href":"/frontend/astro"}]},{"tab":"Mobile (Flutter)","pages":[{"title":"Mobile (Flutter)","href":"/mobile/flutter"}]},{"tab":"Shared","pages":[{"title":"Shared","href":"/shared"}]}]},"basePath":"","title":"Fieldforce Module - Monorepo","buildId":"b48c568d22cf","dynamics":[],"chunks":[]}