Context Web Context Load Fresh Connect Stack

Context

Your spawn_agent

STEP 1: Initialize comprehensive Fresh + ConnectRPC context loading session

• CREATE session state file: /tmp/fresh-connect-context-$SESSION_ID.json
• SET initial state:

  {
    "sessionId": "$SESSION_ID",
    "timestamp": "$(date -Iseconds)",
    "phase": "initialization",
    "architecture_type": "auto-detect",
    "frontend_detected": false,
    "backend_detected": false,
    "integration_patterns": [],
    "documentation_loaded": {},
    "project_analysis": {},
    "context_areas": [
      "architecture_overview",
      "project_structure",
      "development_workflow",
      "integration_patterns",
      "production_features"
    ],
    "checkpoints": []
  }
  

• CREATE context workspace: /tmp/fresh-connect-context-$SESSION_ID/

STEP 2: Project architecture detection and analysis

TRY:

• Think deeply about the optimal Fresh + ConnectRPC architecture patterns based on the detected project structure

• ANALYZE project structure from Context section

• DETERMINE Fresh + ConnectRPC architecture type:

  IF Fresh indicators found AND Go backend indicators found:

  • SET architecture_type = "full_stack_fresh_connect"
  • ENABLE comprehensive full-stack context loading
  • PRIORITIZE: Integration patterns, API proxy setup, type safety

  ELSE IF Fresh indicators found AND NOT Go backend:

  • SET architecture_type = "fresh_frontend_only"
  • FOCUS on Fresh-specific patterns and potential ConnectRPC integration
  • PRIORITIZE: Frontend architecture, potential backend integration

  ELSE IF Go backend indicators found AND NOT Fresh:

  • SET architecture_type = "connectrpc_backend_only"
  • FOCUS on ConnectRPC service patterns and frontend integration readiness
  • PRIORITIZE: Backend architecture, API design, frontend integration prep

  ELSE:

  • SET architecture_type = "greenfield_setup"
  • PROVIDE comprehensive setup guidance for new Fresh + ConnectRPC project
  • PRIORITIZE: Project initialization, architecture decisions, tooling setup

CATCH (project_analysis_failed):

• LOG analysis issues to session state
• CONTINUE with generic Fresh + ConnectRPC guidance
• PROVIDE manual project setup instructions

STEP 3: Adaptive documentation loading based on detected architecture

CASE architecture_type: WHEN "full_stack_fresh_connect":

• Think harder about full-stack integration patterns and potential architectural challenges
• USE spawn_agent tool for parallel documentation loading with 5 specialized agents:
  1. Fresh Architecture Agent: Load Fresh 2.0 Islands, SSR, routing patterns
     • SAVE findings to: /tmp/fresh-connect-context-$SESSION_ID/fresh-architecture.json
  2. ConnectRPC Integration Agent: Load Go ConnectRPC, buf.build, protobuf patterns
     • SAVE findings to: /tmp/fresh-connect-context-$SESSION_ID/connectrpc-integration.json
  3. API Proxy Patterns Agent: Load proxy configuration, CORS, type safety
     • SAVE findings to: /tmp/fresh-connect-context-$SESSION_ID/api-proxy-patterns.json
  4. Development Workflow Agent: Load Deno tasks, hot reload, Docker setup
     • SAVE findings to: /tmp/fresh-connect-context-$SESSION_ID/dev-workflow.json
  5. Production Deployment Agent: Load deployment, monitoring, security patterns
     • SAVE findings to: /tmp/fresh-connect-context-$SESSION_ID/production-patterns.json

WHEN "fresh_frontend_only":

• EXECUTE focused Fresh documentation loading:
  • Think deeply about Fresh 2.0 architecture and integration capabilities
  • LOAD: Fresh Islands, routing, Preact signals, API integration patterns
  • FOCUS: Preparing for potential ConnectRPC backend integration
  • PROVIDE: Backend integration readiness assessment

WHEN "connectrpc_backend_only":

• EXECUTE focused ConnectRPC documentation loading:
  • Think harder about ConnectRPC service design and frontend integration
  • LOAD: Go ConnectRPC, protobuf schemas, CORS handling, API design
  • FOCUS: Frontend-ready API design and integration patterns
  • PROVIDE: Fresh frontend integration guidance

WHEN "greenfield_setup":

• EXECUTE comprehensive setup documentation loading:
  • LOAD: Project initialization, architecture decisions, tooling setup
  • FOCUS: Best practices for Fresh + ConnectRPC project creation
  • PROVIDE: Step-by-step project setup guidance

STEP 4: Comprehensive documentation fetching and context synthesis

TRY:

Core Framework Documentation:

1. Fresh Framework Context

   • TRY WebFetch: https://fresh.deno.dev/docs/introduction
   • FOCUS: Islands architecture, SSR, routing, deployment
   • EXTRACT: Key concepts, integration patterns, best practices
   • FALLBACK: Use embedded documentation if fetch fails

2. Fresh 2.0 Evolution

   • TRY WebFetch: https://deno.com/blog/an-update-on-fresh
   • FOCUS: New features, migration guidance, alpha stability
   • EXTRACT: Production readiness, breaking changes, roadmap
   • FALLBACK: Reference cached alpha documentation patterns

3. ConnectRPC Go Documentation

   • TRY WebFetch: https://connectrpc.com/docs/go/getting-started
   • FOCUS: Service implementation, middleware, testing
   • EXTRACT: Best practices, error handling, performance patterns
   • FALLBACK: Use embedded Go service patterns

4. ConnectRPC Web Integration

   • TRY WebFetch: https://connectrpc.com/docs/web/getting-started
   • FOCUS: Browser client setup, transport configuration
   • EXTRACT: Integration patterns, debugging, optimization
   • FALLBACK: Reference client setup examples below

5. Protocol Buffers Schema Design

   • TRY WebFetch: https://developers.google.com/protocol-buffers/docs/proto3
   • FOCUS: Schema design, evolution, best practices
   • EXTRACT: Type safety, versioning, performance considerations
   • FALLBACK: Use embedded protobuf best practices

CATCH (documentation_fetch_failed):

• LOG failed sources to session state with specific error details
• CONTINUE with available documentation and embedded examples
• PROVIDE comprehensive manual documentation references
• SAVE detailed fallback resources list with alternative sources

STEP 5: Project-specific context organization and synthesis

• Think deeply about integrating all loaded context into actionable guidance for the specific project architecture

• ORGANIZE loaded context by architecture domains:

  • Frontend Architecture: Fresh Islands, SSR, client-side state
  • Backend Services: ConnectRPC handlers, middleware, testing
  • Integration Layer: API proxy, CORS, type safety
  • Development Experience: Hot reload, task automation, debugging
  • Production Deployment: Docker, monitoring, security
  • Type Safety: End-to-end type flow, schema evolution

• SYNTHESIZE project-specific guidance with comprehensive analysis:

  • Integration patterns tailored to detected project structure
  • Optimization strategies for current technology stack
  • Migration paths for architecture evolution with risk assessment
  • Performance considerations and bottleneck prevention
  • Security best practices for the specific stack combination

STEP 6: Session state management and context completion

• UPDATE session state with loaded context summary
• SAVE context cache: /tmp/fresh-connect-context-cache-$SESSION_ID.json
• CREATE comprehensive context summary report
• MARK completion checkpoint

FINALLY:

• ARCHIVE context session data for future reference
• PROVIDE context loading summary with key integration areas
• CLEAN UP temporary processing files: /tmp/fresh-connect-temp-$SESSION_ID-*

Essential Integration Patterns

Core Architecture Components (loaded into context):

1. Package Installation (BSR/Buf Schema Registry)

Buf.build Package Integration:

# Install from Buf Schema Registry
deno install npm:@buf/wcygan_hello.bufbuild_es

Dependencies Configuration Pattern:

// deno.json imports section
{
  "imports": {
    "@fresh/core": "jsr:@fresh/core@^2.0.0-alpha.22",
    "@preact/signals": "npm:@preact/signals@^1.3.0",
    "@connectrpc/connect": "npm:@connectrpc/connect@^2.0.0",
    "@connectrpc/connect-web": "npm:@connectrpc/connect-web@^2.0.0",
    "@buf/your_org_schema.bufbuild_es": "npm:@buf/your_org_schema.bufbuild_es@^2.5.2"
  },
  "nodeModulesDir": "auto"
}

2. API Proxy Route (Critical for Frontend-Backend Communication)

// frontend/routes/api/[...path].ts
import { type FreshContext } from "@fresh/core";

const BACKEND_URL = Deno.env.get("BACKEND_URL") || "http://localhost:3007";

export async function handler(req: Request, _ctx: FreshContext) {
  const url = new URL(req.url);
  const backendUrl = `${BACKEND_URL}${url.pathname.replace("/api", "")}`;

  const response = await fetch(backendUrl, {
    method: req.method,
    headers: req.headers,
    body: req.body,
  });

  // Clone response with CORS headers
  const corsHeaders = new Headers(response.headers);
  corsHeaders.set("Access-Control-Allow-Origin", "*");
  corsHeaders.set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
  corsHeaders.set("Access-Control-Allow-Headers", "Content-Type, Connect-Protocol-Version");

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers: corsHeaders,
  });
}

3. Frontend Island Component with ConnectRPC Client

// frontend/islands/GreeterApp.tsx
import { useSignal } from "@preact/signals";
import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { GreeterService } from "@buf/wcygan_hello.bufbuild_es/hello/v1/hello_connect";

const transport = createConnectTransport({
  baseUrl: "/api",
  useBinaryFormat: false,
});

const client = createClient(GreeterService, transport);

export function GreeterApp() {
  const name = useSignal("");
  const greeting = useSignal("");
  const loading = useSignal(false);

  const handleSubmit = async (e: Event) => {
    e.preventDefault();
    loading.value = true;

    try {
      const response = await client.sayHello({ name: name.value });
      greeting.value = response.message;
    } catch (error) {
      greeting.value = `Error: ${error.message}`;
    } finally {
      loading.value = false;
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={name.value}
        onInput={(e) => name.value = e.currentTarget.value}
        placeholder="Enter your name"
      />
      <button type="submit" disabled={loading.value}>
        {loading.value ? "Loading..." : "Say Hello"}
      </button>
      {greeting.value && <p>{greeting.value}</p>}
    </form>
  );
}

4. Backend ConnectRPC Service

// backend/cmd/server/main.go
package main

import (
    "log"
    "net/http"
    "github.com/connectrpc/connect-go"
    hellov1 "buf.build/gen/go/wcygan/hello/protocolbuffers/go/hello/v1"
    "buf.build/gen/go/wcygan/hello/connectrpc/go/hello/v1/hellov1connect"
)

type GreeterService struct{}

func (s *GreeterService) SayHello(
    ctx context.Context,
    req *connect.Request[hellov1.SayHelloRequest],
) (*connect.Response[hellov1.SayHelloResponse], error) {
    name := req.Msg.Name
    if name == "" {
        name = "World"
    }

    return connect.NewResponse(&hellov1.SayHelloResponse{
        Message: fmt.Sprintf("Hello, %s!", name),
    }), nil
}

func main() {
    greeter := &GreeterService{}
    path, handler := hellov1connect.NewGreeterServiceHandler(greeter)

    mux := http.NewServeMux()
    mux.Handle(path, handler)

    // Add CORS middleware
    corsHandler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Access-Control-Allow-Origin", "*")
        w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
        w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Connect-Protocol-Version")

        if r.Method == "OPTIONS" {
            w.WriteHeader(http.StatusOK)
            return
        }

        mux.ServeHTTP(w, r)
    })

    log.Fatal(http.ListenAndServe(":3007", corsHandler))
}

5. Buf.build Registry Configuration

NPM Registry Setup:

# .npmrc configuration
@buf:registry=https://buf.build/gen/npm/v1/

Project Structure Integration:

project/
├── frontend/              # Fresh 2.0 application
│   ├── deno.json         # Dependencies and tasks
│   ├── .npmrc            # Buf.build registry config
│   ├── routes/
│   │   └── api/[...path].ts  # API proxy for ConnectRPC
│   └── islands/          # Interactive components
├── backend/              # Go ConnectRPC service
│   ├── go.mod           # Go dependencies
│   ├── cmd/server/      # Main server implementation
│   └── internal/        # Service logic
├── proto/               # Protocol Buffer schemas
├── docker-compose.yml   # Development orchestration
└── deno.json           # Root task automation

6. Docker Compose for Local Development

# docker-compose.yml