architecture-advisor

Architecture Advisor

Language-adaptive architecture guide. Apply the section matching the project's language.

Language Detection

Identify language from:

• File extensions: .go → Go, .ts/.tsx → TypeScript
• Project files: go.mod → Go, package.json + tsconfig.json → TypeScript

---

Go (Layered Architecture)

Layer Structure

<source_root>/
├── handler/         # HTTP/gRPC handlers (thin — delegate to usecase)
├── usecase/         # Application logic (orchestrates domain)
├── domain/          # Entities, repository interfaces, service interfaces
└── infrastructure/  # DB implementations, external API clients, gRPC stubs

Dependency Rule

handler → usecase → domain ← infrastructure

• Domain must never import infrastructure packages
• No global state — inject all dependencies via constructor
• context.Context must be the first parameter in all functions

Constructor Injection Pattern

// domain/repository.go
type UserRepository interface {
    FindByID(ctx context.Context, id string) (*User, error)
    Save(ctx context.Context, user *User) error
}

// usecase/user_usecase.go
type UserUsecase struct {
    repo UserRepository
}

func NewUserUsecase(repo UserRepository) *UserUsecase {
    return &UserUsecase{repo: repo}
}

// handler/user_handler.go
type UserHandler struct {
    uc *usecase.UserUsecase
}

func NewUserHandler(uc *usecase.UserUsecase) *UserHandler {
    return &UserHandler{uc: uc}
}

gRPC Server Pattern

// handler/grpc/user_server.go
type UserServer struct {
    pb.UnimplementedUserServiceServer
    uc *usecase.UserUsecase
}

func (s *UserServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
    user, err := s.uc.GetUser(ctx, req.GetId())
    if err != nil {
        return nil, status.Errorf(codes.NotFound, "user not found: %v", err)
    }
    return &pb.GetUserResponse{User: toProto(user)}, nil
}

Error Handling

// Use fmt.Errorf with %w for wrapping
return nil, fmt.Errorf("usecase.GetUser: %w", err)

// Sentinel errors in domain
var ErrNotFound = errors.New("not found")
var ErrAlreadyExists = errors.New("already exists")

Anti-patterns to Flag

• Handler importing infrastructure package directly
• Global var db *sql.DB (use constructor injection)
• context.TODO() in production code (use passed context)
• Business logic inside HTTP handler function

---

TypeScript / Node.js

Layer Structure

REST API / Backend

<source_root>/
├── api/             # Route handlers (thin — delegate to usecase)
├── usecase/         # Application logic
├── domain/          # Entities, repository interfaces
└── infrastructure/  # DB implementations, external clients

Mastra / Agent System

<source_root>/
├── agents/          # Agent definitions (LLM + tools + instructions)
├── tools/           # Tool implementations (atomic actions)
├── workflows/       # Multi-step orchestration (coordinates agents/tools)
└── lib/             # Shared utilities, types, config

Backend Dependency Rule

api → usecase → domain ← infrastructure

• No any types in domain or usecase layers
• Dependency injection via constructor, not module-level singletons
• Use zod for all external input validation at the API boundary

Mastra Agent Pattern

// tools/fetch-user-tool.ts
export const fetchUserTool = createTool({
  id: 'fetch-user',
  description: 'Fetch user data by ID',
  inputSchema: z.object({ userId: z.string() }),
  outputSchema: z.object({ id: z.string(), name: z.string() }),
  execute: async ({ context }) => {
    return userRepository.findById(context.userId);
  },
});

// agents/user-agent.ts
export const userAgent = new Agent({
  name: 'UserAgent',
  instructions: 'You help manage user data...',
  model: anthropic('claude-sonnet-4-6'),
  tools: { fetchUserTool },
});

Result Pattern for Error Handling

type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };

async function createUser(input: CreateUserInput): Promise<Result<User>> {
  if (!input.name) {
    return { ok: false, error: new Error('Name is required') };
  }
  const user = await userRepository.save(new User(input));
  return { ok: true, value: user };
}

Anti-patterns to Flag

• any type in domain or usecase layer
• Tool with side effects that can't be rolled back (prefer idempotent tools)
• Business logic inside API route handler
• Agent with too many tools (> 10) — split into specialized agents
• Workflow step with no error handling

Related Skills

• pr-reviewer-3a — Architecture review in PR context
• code-explorer — Visualize current dependency structure