Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
75 lines (63 loc) · 3.12 KB

DEVELOPMENT.md

File metadata and controls

75 lines (63 loc) · 3.12 KB

Service Implementation Blueprint

Use this document as a reference when implementing or finalizing any service (S3, SQS, SNS, DynamoDB, etc.) in the LocalStack UI. This ensures consistency in architecture, UI, and UX.

1. Backend: Data Layer (internal/aws/client.go)

For every service, implement the following in the Go client:

  • Data Structures:
    • [Service]Info: Lightweight struct for listing (e.g., BucketInfo, QueueInfo).
    • [Service]Detail or Value: Detailed struct for individual item view (e.g., SecretValue, S3Object).
  • Client Implementation:
    • New[Service]Client: Factory function using GetConfig.
    • List[Service]s: Returns a slice of Info structs.
    • Get[Service]: Returns details for a specific resource ID.
    • Create[Service]: Handles resource creation.
    • Update[Service]: (If applicable) Handles resource updates.
    • Delete[Service]: Handles resource deletion.

2. Backend: API Layer (main.go)

Register the REST endpoints using the standard library's ServeMux.

  • Endpoints:
    • GET /api/[service]: List resources.
    • POST /api/[service]: Create resource.
    • GET /api/[service]/{id}: Get resource details.
    • PUT /api/[service]/{id}: Update resource.
    • DELETE /api/[service]/{id}: Delete resource.
  • Handler Pattern:
    1. Initialize specific AWS client.
    2. Parse path variables or JSON body.
    3. Call client method.
    4. Return JSON response with correct headers/status codes.

3. Frontend: State Management (web/templates/index.html)

In the Alpine.js app() function:

  • State Variables:
    • [resources]: Array for the list view.
    • [resource]Search: String for filtering.
    • show[Resource]Modal: Boolean for UI control.
    • is[Action]ing: Boolean for loading states.
  • Methods:
    • fetch[Resources]: Calls the list API.
    • selectService(name): Triggers the initial fetch.
    • openCreate[Resource]: Resets form and opens modal.
    • view[Resource](id): Fetches details and opens view/edit modal.
    • save/update[Resource]: Logic for PUT/POST.
    • delete[Resource](id): Logic for DELETE with confirm().

4. Frontend: UI Components

Follow the Shadcn UI aesthetic:

  • List View:
    • Header with title, description, Refresh button, and "Create" button.
    • Search input for real-time filtering.
    • Data table with neutral borders and hover effects.
  • Modals:
    • Consistent layout: Header (Title + Close), Body (Scrollable content), Footer (Actions).
    • Backdrop blur (backdrop-blur-sm).
  • UX Patterns:
    • KV Editor: If the resource is an object/JSON (like Secrets or DynamoDB items), provide a Key-Value grid.
    • Raw Mode: Always provide a Raw/JSON editor fallback.
    • Toasts: Use this.addToast(msg, type) for all async actions.
    • Clipboard: Provide "Copy" buttons for IDs, ARNs, and values.

Example: The "Secrets Manager" Pattern

  1. List API returns Names + Descriptions.
  2. Detail API returns the Secret String.
  3. UI detects if the string is JSON.
  4. If JSON: Render secretKV array (key-value rows).
  5. On Save: Serialize KV back to JSON string and send to Go API.