Service Layer Architecture

Controller-service-query layered API architecture with data enrichment and parallel fetching. Use when building REST APIs or GraphQL resolvers with clean separation of concerns. Triggers on API architecture, service layer, controller pattern, data enrichment, REST API.

Security Scan

This is an instruction-only skill that provides architecture guidance for controller–service–query layers; its requirements and instructions are consistent with that purpose and it does not request credentials or install code automatically.

Purpose & Capability

Name/description match the content: the skill is architecture guidance for REST/GraphQL layers and the SKILL.md contains only code examples and patterns relevant to that purpose. There are no unrelated env vars, binaries, or config paths requested.

Instruction Scope

Runtime instructions are example code and design rules (controllers, services, queries, Promise.all). They do not instruct the agent to read arbitrary files, access credentials, or transmit data to external endpoints. Some recommendations (e.g., "always use .lean()") are opinionated and may not fit every scenario, but this is design guidance rather than malicious behavior.

Install Mechanism

The skill is instruction-only (no install spec), which is lowest risk. README includes an npx add command pointing to a GitHub tree URL and copy instructions that assume local skill directories; fetching code from an external repo is optional but carries the usual risk—verify the remote repository before running any fetch/install commands.

Credentials

No environment variables, credentials, or config paths are requested; the skill does not ask for secrets and its example code uses generic query/service calls without requiring external keys.

Persistence & Privilege

Flags are default (always:false, user-invocable:true). The skill does not request persistent presence or system-wide changes and has no install-time behavior that would modify other skills or agent config.

Assessment

This skill is a benign, instruction-only guide for layering controllers, services, and queries. Before you copy or run any remote code referenced in the README (the npx add GitHub URL or repository copies), inspect that repository yourself — fetching and executing code from third-party repos is where risk appears. Also treat design rules as guidance (for example, .lean() improves performance in many MongoDB reads but isn't always appropriate); review and adapt snippets to your application's correctness, security, and error-handling needs. If you want higher assurance, ask the publisher for a canonical source or inspect the repository history before using the code.

Clean, performant API layers with proper separation of concerns and parallel data fetching.

---

When to Use

• Building REST APIs with complex data aggregation
• GraphQL resolvers needing data from multiple sources
• Any API where responses combine data from multiple queries
• Systems needing testable, maintainable code

---

Three-Layer Architecture

┌─────────────────────────────────────────────────────┐
│  Controllers   │  HTTP handling, validation        │
├─────────────────────────────────────────────────────┤
│  Services      │  Business logic, data enrichment  │
├─────────────────────────────────────────────────────┤
│  Queries       │  Database access, raw data fetch  │
└─────────────────────────────────────────────────────┘

---

Layer 1: Controllers (HTTP Only)

// controllers/Entity.ts
import { getEntity, getEntities } from "../services/Entity";

const router = new Router();

router.get("/entity/:entityId", async (ctx) => {
  const { entityId } = ctx.params;

  if (!entityId) {
    ctx.status = 400;
    ctx.body = { error: "Invalid entity ID" };
    return;
  }

  const entity = await getEntity(entityId);
  
  if (!entity) {
    ctx.status = 404;
    ctx.body = { error: "Entity not found" };
    return;
  }
  
  ctx.status = 200;
  ctx.body = entity;
});

---

Layer 2: Services (Business Logic)

// services/Entity.ts
import { queries } from "@common";

export const getEntityData = async (entity: RawEntity): Promise<EnrichedEntity> => {
  // Parallel fetch all related data
  const [metadata, score, activity, location] = await Promise.all([
    queries.getMetadata(),
    queries.getLatestScore(entity.id),
    queries.getActivity(entity.id),
    queries.getLocation(entity.slotId),
  ]);

  // Transform and combine
  return {
    ...entity,
    bonded: entity.bonded / Math.pow(10, metadata.decimals),
    total: score?.total ?? 0,
    location: location?.city,
    activity: {
      activeCount: activity?.active?.length ?? 0,
      inactiveCount: activity?.inactive?.length ?? 0,
    },
  };
};

export const getEntity = async (entityId: string): Promise<EnrichedEntity | null> => {
  const entity = await queries.getEntityById(entityId);
  if (!entity) return null;
  return getEntityData(entity);
};

export const getEntities = async (): Promise<EnrichedEntity[]> => {
  const all = await queries.allEntities();
  const enriched = await Promise.all(all.map(getEntityData));
  return enriched.sort((a, b) => b.total - a.total);
};

---

Layer 3: Queries (Database Access)

// queries/Entities.ts
import { EntityModel } from "../models";

export const allEntities = async () => {
  return EntityModel.find({}).lean();  // Always use .lean()
};

export const getEntityById = async (id: string) => {
  return EntityModel.findOne({ id }).lean();
};

export const validEntities = async () => {
  return EntityModel.find({ valid: true }).lean();
};

---

Parallel Data Fetching

// BAD: Sequential (slow)
const metadata = await queries.getMetadata();
const score = await queries.getScore(id);
const location = await queries.getLocation(id);
// Time: sum of all queries

// GOOD: Parallel (fast)
const [metadata, score, location] = await Promise.all([
  queries.getMetadata(),
  queries.getScore(id),
  queries.getLocation(id),
]);
// Time: max of all queries

---

Layer Responsibilities

Task	Layer
Parse request params	Controller
Validate input	Controller
Set HTTP status	Controller
Combine multiple queries	Service
Transform data	Service
Sort/filter results	Service
Run database query	Query

---

Related Skills

• Related: postgres-job-queue — Background job processing
• Related: realtime/websocket-hub-patterns — Real-time updates from services

---

NEVER Do

• NEVER put database queries in controllers — Violates separation
• NEVER put HTTP concerns in services — Services must be reusable
• NEVER fetch related data sequentially — Use Promise.all
• NEVER skip .lean() on read queries — 5-10x faster
• NEVER expose raw database errors — Transform to user-friendly messages