Self Serve Dev

LFX One Development Guide

You are helping a contributor build within the LFX One codebase. This skill handles all development work: creating new features, fixing bugs, modifying existing code, refactoring, and full end-to-end feature builds.

Important: You are integrating features within existing architecture — not making architectural decisions. If the work requires changes to routing, auth, middleware, or infrastructure, flag it for a code owner.

Pre-edit hygiene

Before every meaningful edit:

1. Re-read the file with view — do not trust prior conversation history. Files change; context drifts.
2. Run yarn check-types after multi-file changes to catch type drift early.
3. Stop and ask if the request conflicts with conventions in CLAUDE.md or .claude/rules/.

Default to small, atomic changes. If a request spans more than one module or touches both client and SSR server, surface that and ask whether to split.

Step 1: Start from Latest Main & Track Work

Follow the "Starting New Work" rule in development-rules.md — checkout main, pull latest, and create a feature branch before writing any code.

Tracking Ticket (JIRA or GitHub Issue)

Before writing code, ensure the work is tracked:

1. Check for an existing ticket — a JIRA ticket in the LFXV2 project, or a GitHub Issue on linuxfoundation/lfx-self-serve (e.g. under an epic on the Kanban board)
2. Create one if needed — JIRA ticket (assign to the current user and current sprint) or a GitHub Issue via gh issue create; don't create both for the same work
3. Branch name must include the ticket: feat/LFXV2-<number>, fix/LFXV2-<number> for JIRA, or feat/issue-<number>, fix/issue-<number> for a GitHub Issue
4. Reference .claude/rules/commit-workflow.md for naming conventions

Step 2: Plan the Feature (Ideation)

Ask the contributor what they're building. Before writing any code, create a plan that answers:

1. What is the feature? — Describe the user-facing behavior
2. What data does it need? — Identify the API endpoints, request/response shapes, and data flow
3. What upstream APIs are required? — List which microservice endpoints the feature depends on
4. Do the upstream microservices already support this? — This is critical (see Step 3)
5. What frontend components are needed? — Pages, shared components, services

Scope for PR Size

Before jumping into code, assess whether the planned work fits in a single PR. PRs that exceed ~1000 lines of diff become significantly harder to review, more likely to introduce bugs, and slower to merge.

• If the feature touches multiple layers (types + backend + frontend) and the total diff is approaching the limit, consider splitting by layer — e.g., shared types first, then backend, then frontend. If all layers fit comfortably under 1000 lines, keep them in one PR.
• If the feature has independent sub-features, split them. A "committee management" feature might break into: list view, create form, edit/delete — each independently deliverable.
• Separate refactors from features — if existing code needs restructuring to support the new feature, do the refactor PR first.
• Generated/mechanical changes get their own PR — bulk renames, formatting, dependency bumps, or migration outputs should not be mixed with hand-written logic.

If the plan looks like it will exceed 1000 lines, propose a PR sequence to the contributor before writing code. Each PR should deliver a cohesive, independently reviewable piece.

If you are unsure where new code should live (a new component, a new module, a new type, a new backend service, or whether to use a user token vs M2M), walk the Placement Decision Trees before continuing.

Determine Workflows

Based on the plan, determine which workflow(s) apply:

Build order is strict: Shared Types → Backend → Frontend Service → Frontend Component. Never skip ahead.

Modifying Existing Features

If the work is a bug fix, enhancement, or refactoring of existing code:

1. Read existing code first — understand what's there before changing it
2. Trace the data flow end-to-end — from API call through service to component template
3. Identify the minimal change with the smallest blast radius
4. Follow the same build order for any new files needed (types → backend → frontend)

Step 3: Validate Backend Support (Backend First)

Before writing any frontend code, verify that the upstream microservice APIs needed for this feature actually exist and support the required operations.

Check the Upstream API Contract

The LFX One backend is a thin proxy layer, it proxies requests to external Go microservices. The feature can only work if those microservices expose the endpoints you need.

See the /lfx skill's references/repo-map.md for the upstream microservice repo list (Queries, Projects, Meetings, Mailing Lists, Committees, Voting, Surveys) with owning repo paths and default peers. For each domain, the key areas to check are: resource types and CRUD operations, query params, pagination, filters, and the external integrations the service owns.

# Read the OpenAPI spec for the full API contract
gh api repos/linuxfoundation/<repo-name>/contents/gen/http/openapi3.yaml \
  --jq '.content' | base64 -d

# Browse the Goa DSL design files
gh api repos/linuxfoundation/<repo-name>/contents/design --jq '.[].name'

# Read a specific Goa design file
gh api repos/linuxfoundation/<repo-name>/contents/design/<file>.go \
  --jq '.content' | base64 -d

If the API Does NOT Exist

STOP. Do not proceed to frontend work. Instead:

1. Switch to the upstream microservice repo — clone it and check if it has its own Claude Code skills (/self-serve-dev, etc.) that should be used for building there
2. Build the required API endpoints in the upstream repo first, following that repo's conventions and skills
3. Get the upstream changes merged and deployed (or at minimum, confirm the API contract is finalized)
4. Then return to this repo to build the proxy layer and frontend

If the API Exists

Confirm:

• The endpoint paths and HTTP methods match what you need
• The request/response schemas have the fields your feature requires
• Query parameters support the filtering/pagination your UI needs

Then proceed to Step 4.

Critical rule: NO mock data, NO placeholder APIs, NO fake responses. Every API call in the frontend must connect to a real, working backend endpoint. If the data doesn't flow end-to-end, the feature is not ready to be built. Do not stub services, hardcode responses, or create temporary mocks to "unblock" frontend work.

Step 4: Required Reading

Read the relevant architecture docs before generating code. These are the source of truth.

Always Read

• CLAUDE.md → "Component Organization Pattern" section — class structure ordering, signal patterns

For Frontend Work

• docs/architecture/frontend/component-architecture.md — Component placement, module structure, PrimeNG wrapper strategy
• docs/architecture/frontend/angular-patterns.md — Signals, change detection, template syntax, inject() pattern
• docs/architecture/frontend/styling-system.md — CSS layers, Tailwind configuration
• docs/architecture/frontend/state-management.md — Service-based state, signal architecture
• docs/architecture/frontend/drawer-pattern.md — Drawer components with lazy loading and charts (if building a drawer)
• .claude/skills/self-serve-dev/references/frontend-code-generation.md — Self Serve frontend generation rules for components, drawers, pagination, and templates

For Backend Work

• docs/architecture/backend/ssr-server.md — Server architecture, route registration
• docs/architecture/backend/logging-monitoring.md — Logger service usage, operation lifecycle, log levels
• docs/architecture/backend/error-handling-architecture.md — Error classification, response format
• docs/architecture/backend/server-helpers.md — Helper patterns, validation, pagination helpers
• docs/architecture/backend/pagination.md — Cursor-based pagination patterns (if endpoint returns lists)

For Shared Package Work

• docs/architecture/shared/package-architecture.md — Package structure, exports, utilities, validators

Step 5: Check What Exists

Before creating anything, check what already exists to avoid duplicates:

# Frontend
ls apps/lfx-one/src/app/modules/                    # Feature modules
ls apps/lfx-one/src/app/shared/components/           # Shared components
ls apps/lfx-one/src/app/shared/services/             # Frontend services

# Backend
ls apps/lfx-one/src/server/controllers/              # Controllers
ls apps/lfx-one/src/server/services/                 # Backend services
ls apps/lfx-one/src/server/routes/                   # Route files

# Shared package
ls packages/shared/src/interfaces/                   # Interfaces
ls packages/shared/src/enums/                        # Enums
ls packages/shared/src/constants/                    # Constants

If related code already exists, read it first and extend it rather than creating new files.

Step 6: Read an Existing Example

Read a representative file in the target area to match the team's current patterns. Pick something in the same module or domain as the work being done.

Step 7: Build

Follow the workflow(s) identified in Step 2. The sections below provide key conventions for each — read the linked reference file for full details, examples, and checklists.

Reminder: Build in strict order — Shared Types → Backend → Frontend Service → Frontend Component. Never build frontend code against APIs that don't exist yet. No mock data, no placeholder services, no hardcoded responses.

Shared Types

Location: packages/shared/src/interfaces/, enums/, or constants/

Key rules: License headers, TypeScript interfaces (not union types), correct file suffixes, barrel exports, never define interfaces locally.

Read references/shared-types.md for full conventions and checklist.

Backend Endpoint

Creates three files: service → controller → route.

Key rules: MicroserviceProxyService for API calls, logger service for logging, next(error) for errors, snake_case operation names, server.ts registration requires code owner.

Read references/backend-endpoint.md for full patterns, examples, and checklist.

Frontend Service

Location: apps/lfx-one/src/app/shared/services/<name>.service.ts

Key rules: providedIn: 'root', inject(HttpClient), catchError for GETs, take(1) for writes, signals can't use rxjs pipes.

Read references/frontend-code-generation.md (Section 2 - service generation) for full patterns, examples, and checklist.

Frontend Component

Key rules: Standalone with direct imports, correct placement per category, 11-section class structure, @if/@for templates, data-testid attributes, flex + gap not space-y.

Read references/frontend-code-generation.md (Section 1 - component generation) for full placement table, examples, and checklist.

Step 8: Validate

Run the full validation suite:

yarn format        # Apply formatting
yarn lint          # Check for linting errors
yarn build         # Verify build succeeds

Fix any issues before finishing.

Step 9: Summary & Next Steps

Provide a clear summary:

• All files created or modified
• Any new shared types and their import paths
• Any actions needed from code owners (route registration, routing changes, etc.)
• How to use the new code (inject services, import components, etc.)

Next step: Run /preflight to validate everything before submitting a PR.