<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Kaziu</title>
    <description>The latest articles on DEV Community by Kaziu (@kaziusan).</description>
    <link>https://dev.to/kaziusan</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F211048%2F802876cd-1431-467c-8ca8-8263ca29514a.jpeg</url>
      <title>DEV Community: Kaziu</title>
      <link>https://dev.to/kaziusan</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/kaziusan"/>
    <language>en</language>
    <item>
      <title>What's a "Blob"? How Browsers Download Files</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:43:28 +0000</pubDate>
      <link>https://dev.to/kaziusan/whats-a-blob-how-browsers-download-files-4b6h</link>
      <guid>https://dev.to/kaziusan/whats-a-blob-how-browsers-download-files-4b6h</guid>
      <description>&lt;p&gt;When you implement a CSV download feature, you run into unfamiliar code like this.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;blob&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Blob&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'text/csv'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;objectURL&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;window&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createObjectURL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nf"&gt;downloadFile&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;objectURL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'data.csv'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;"Blob?" "Create a URL?" "Then download it? From where?" This post will clear all that up.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's a Blob?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Blob = a "chunk of data" that can hold anything&lt;/strong&gt;. To the browser, it's "something like a file." It can hold text, images, CSV, PDF, whatever, and it can carry a type label (MIME type) like "this is CSV."&lt;/p&gt;

&lt;p&gt;To tell the browser "this is a file, please save it," you need to turn the data into &lt;strong&gt;"file form" = a Blob&lt;/strong&gt;. Left as raw text data, it's just treated as a plain string.&lt;/p&gt;

&lt;h2&gt;
  
  
  The letter analogy
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Letter analogy&lt;/th&gt;
&lt;th&gt;The real thing&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;The document (the CSV contents)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;response.data&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Putting it in an envelope&lt;/td&gt;
&lt;td&gt;&lt;code&gt;new Blob(...)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Sticking on an address label&lt;/td&gt;
&lt;td&gt;The URL from &lt;code&gt;createObjectURL&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Mailing it = saving&lt;/td&gt;
&lt;td&gt;Clicking &lt;code&gt;&amp;lt;a download&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  What the code means
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// ① Receive it as binary (forget this and your CSV can get corrupted)&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;response&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;responseType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'blob'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="c1"&gt;// ② Put the data into a "CSV file" box&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;blob&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Blob&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'text/csv'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="c1"&gt;// ③ Issue a temporary URL that points to that box&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;objectURL&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;window&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createObjectURL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;blob&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="c1"&gt;// ④ Have that URL saved as a file&lt;/span&gt;
&lt;span class="nf"&gt;downloadFile&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;objectURL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'data.csv'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The key is &lt;strong&gt;the URL in ③&lt;/strong&gt;. It's &lt;strong&gt;not&lt;/strong&gt; a location on a server like &lt;code&gt;https://...&lt;/code&gt;;&lt;br&gt;
it's &lt;strong&gt;a label pointing to data you already have on hand (in the browser's memory)&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;What's inside &lt;code&gt;downloadFile&lt;/code&gt; is simple too: "just create an &lt;code&gt;&amp;lt;a&amp;gt;&lt;/code&gt; with a &lt;code&gt;download&lt;/code&gt; attribute and click it with JS."&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;downloadFile&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;url&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;filename&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createElement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'a'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;href&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;url&lt;/span&gt;
  &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;download&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;filename&lt;/span&gt;
  &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;click&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Since the link points to a &lt;code&gt;blob:&lt;/code&gt; URL, &lt;strong&gt;it doesn't go to the server; it saves the data you have on hand straight to a file&lt;/strong&gt;.&lt;br&gt;
So even though we say "download the URL," &lt;strong&gt;it's not re-downloading anything; it's just saving data you already have&lt;/strong&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  Extra: clean up URLs when you're done
&lt;/h2&gt;

&lt;p&gt;A URL from &lt;code&gt;createObjectURL&lt;/code&gt; keeps holding onto memory, so it's good manners to release it when you're done.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nb"&gt;window&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="no"&gt;URL&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;revokeObjectURL&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;objectURL&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Summary
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Blob&lt;/strong&gt; = to the browser, "a file-like chunk of data"&lt;/li&gt;
&lt;li&gt;The URL from &lt;strong&gt;&lt;code&gt;createObjectURL&lt;/code&gt;&lt;/strong&gt; is &lt;strong&gt;a label pointing to data on hand&lt;/strong&gt;, not to a server&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Clicking &lt;code&gt;&amp;lt;a download&amp;gt;&lt;/code&gt;&lt;/strong&gt; saves that data as a file&lt;/li&gt;
&lt;li&gt;This flow is &lt;strong&gt;the same for any file&lt;/strong&gt;: images, PDFs, ZIPs, and so on&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>javascript</category>
      <category>tutorial</category>
      <category>typescript</category>
      <category>webdev</category>
    </item>
    <item>
      <title>Testing Webhook Delivery by Temporarily Exposing Your Local Server with ngrok</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:43:23 +0000</pubDate>
      <link>https://dev.to/kaziusan/testing-webhook-delivery-by-temporarily-exposing-your-local-server-with-ngrok-1bgb</link>
      <guid>https://dev.to/kaziusan/testing-webhook-delivery-by-temporarily-exposing-your-local-server-with-ngrok-1bgb</guid>
      <description>&lt;h2&gt;
  
  
  Introduction
&lt;/h2&gt;

&lt;p&gt;I'm building a &lt;strong&gt;webhook sending feature&lt;/strong&gt; for a SaaS product.&lt;/p&gt;

&lt;p&gt;Our customers sync data from the SaaS into their own core business systems, but right now they do it by &lt;strong&gt;polling&lt;/strong&gt; the SaaS API (asking for changes at regular intervals), so updates don't show up in real time.&lt;br&gt;
The goal is to &lt;strong&gt;send a webhook to the customer's system the moment data changes on the SaaS side, so their core system's data updates automatically&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;The tricky part was &lt;strong&gt;how to set up the "receiving end" locally&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Users can enter any destination URL they like, so if someone specifies an address on an internal network, it opens the door to an &lt;strong&gt;SSRF (Server-Side Request Forgery)&lt;/strong&gt; attack, where the server is tricked into sending requests to internal systems.&lt;br&gt;
As a countermeasure, I added a restriction to &lt;strong&gt;only send to HTTPS URLs that are publicly reachable on the internet&lt;/strong&gt;. That means even if I spin up a receiver on my own &lt;code&gt;localhost&lt;/code&gt;, I can't send to it.&lt;/p&gt;
&lt;h2&gt;
  
  
  What is ngrok?
&lt;/h2&gt;

&lt;p&gt;It's &lt;strong&gt;a tool that gives a server running on your own PC a temporary public URL&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;External service ──→ https://xxxx.ngrok-free.app ──(relayed by ngrok)──→ localhost:3000 on your PC
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Since you get a public HTTPS URL, you can check delivery locally without loosening the SSRF checks.&lt;br&gt;
While it's running, you can also inspect the contents of incoming requests at &lt;code&gt;http://localhost:3040&lt;/code&gt;.&lt;/p&gt;
&lt;h2&gt;
  
  
  How to use it
&lt;/h2&gt;
&lt;h3&gt;
  
  
  1. Create a dummy receiver
&lt;/h3&gt;

&lt;p&gt;A server that just accepts a POST, prints what it got, and returns 200.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="c1"&gt;# webhook_receiver.py&lt;/span&gt;
&lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;http&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="nc"&gt;BaseHTTPRequestHandler&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;HTTPServer&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="n"&gt;json&lt;/span&gt;

&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Handler&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;BaseHTTPRequestHandler&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;do_POST&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="n"&gt;body&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;rfile&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;read&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'Content-Length'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;print&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;dict&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="k"&gt;print&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;dumps&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;loads&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;body&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;indent&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ensure_ascii&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="kc"&gt;False&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;send_response&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;  &lt;span class="c1"&gt;# Change this to 500 or 401 to check how failures are handled&lt;/span&gt;
        &lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;end_headers&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="nc"&gt;HTTPServer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'0.0.0.0'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;4000&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Handler&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;serve_forever&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;python3 webhook_receiver.py
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  2. Expose it with ngrok
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;brew install ngrok
ngrok config add-authtoken &lt;span class="o"&gt;&amp;lt;&lt;/span&gt;your-token&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
ngrok http 4000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The &lt;code&gt;https://xxxx.ngrok-free.app&lt;/code&gt; it displays is your public URL.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Set the URL on the sending side and try it
&lt;/h3&gt;

&lt;p&gt;Put this URL into the app's webhook settings and update some data, and the received JSON shows up in the receiver's terminal.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"eventId"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"event_123"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"order"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"occurredAt"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-01-01T12:00:00+09:00"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"order"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Sample order"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Things to watch out for
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;The public URL is accessible to anyone, so shut it down as soon as you're done checking&lt;/li&gt;
&lt;li&gt;Don't send real data; test with dummy data&lt;/li&gt;
&lt;li&gt;Check the detailed cases (errors, timeouts, etc.) in automated tests by stubbing out HTTP, and use ngrok for the final end-to-end check&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Summary
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Polling isn't real-time, so I'm building webhooks that send changes immediately&lt;/li&gt;
&lt;li&gt;The SSRF protection only allows sending to public URLs, but with ngrok you can test locally without loosening those checks&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>webdev</category>
    </item>
    <item>
      <title>"Same Leading Column on Two Indexes? Ain't One of 'Em a Waste?" — How to Find and Drop Redundant Indexes</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:41:33 +0000</pubDate>
      <link>https://dev.to/kaziusan/same-leading-column-on-two-indexes-aint-one-of-em-a-waste-how-to-find-and-drop-redundant-419a</link>
      <guid>https://dev.to/kaziusan/same-leading-column-on-two-indexes-aint-one-of-em-a-waste-how-to-find-and-drop-redundant-419a</guid>
      <description>&lt;p&gt;Have you ever been looking through a table's indexes and spotted a pair like this sitting side by side?&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;KEY&lt;/span&gt;        &lt;span class="sb"&gt;`idx_logs_on_import_id`&lt;/span&gt;            &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`import_id`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;UNIQUE&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt; &lt;span class="sb"&gt;`idx_logs_on_import_id_and_file`&lt;/span&gt;   &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`import_id`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="sb"&gt;`file_path`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Spoiler: &lt;strong&gt;you can usually drop the single-column one on top&lt;/strong&gt;. In this post I'll walk through "why you can drop it," "whether you really should (and the exception where you can't)," "how to find these mechanically," and "how to remove them safely."&lt;/p&gt;




&lt;h2&gt;
  
  
  Why the single &lt;code&gt;(import_id)&lt;/code&gt; index is redundant
&lt;/h2&gt;

&lt;p&gt;The key is a property of B-Tree indexes: &lt;strong&gt;the "leftmost prefix" of a composite index also works as a single-column index&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;An index on &lt;code&gt;(import_id, file_path)&lt;/code&gt; is sorted first by &lt;code&gt;import_id&lt;/code&gt;, and then by &lt;code&gt;file_path&lt;/code&gt; within that. Think of a phone book sorted by "last name → first name."&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;"Look up by last name only" → works (it's sorted from the left)&lt;/li&gt;
&lt;li&gt;"Look up by first name only" → doesn't work&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In the same way, &lt;code&gt;(import_id, file_path)&lt;/code&gt; gives you:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;WHERE import_id = ?&lt;/code&gt; → &lt;strong&gt;uses the index&lt;/strong&gt; (the leftmost column is &lt;code&gt;import_id&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;WHERE file_path = ?&lt;/code&gt; → doesn't (the second column can't be used on its own)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So a &lt;code&gt;WHERE import_id = ?&lt;/code&gt; lookup is fully covered by the composite index. &lt;strong&gt;The single &lt;code&gt;(import_id)&lt;/code&gt; index does exactly the same job as the composite one.&lt;/strong&gt;&lt;/p&gt;




&lt;h2&gt;
  
  
  Redundant indexes actually hurt
&lt;/h2&gt;

&lt;p&gt;You might think, "If it's just unused, what's the harm?" But indexes aren't free.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Slower writes&lt;/strong&gt;: every INSERT / UPDATE / DELETE has to update every index. That one redundant index adds wasted update cost every single time.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Eats disk and memory&lt;/strong&gt;: an index exists as its own structure, separate from the actual data. It also puts pressure on the buffer pool.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Gives the optimizer pointless extra options&lt;/strong&gt;: more candidates to consider when building an execution plan.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Zero benefit for reads (the composite covers it), but you keep paying the write cost. That's why redundant indexes should go.&lt;/p&gt;




&lt;h2&gt;
  
  
  How to find them mechanically
&lt;/h2&gt;

&lt;p&gt;Checking every table by eye isn't realistic. Let the tools do it.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. MySQL's built-in view &lt;code&gt;sys.schema_redundant_indexes&lt;/code&gt; (recommended, nothing to install)
&lt;/h3&gt;

&lt;p&gt;On MySQL 5.7 or later, it works with no extra installation. It detects leftmost-prefix duplicates and &lt;strong&gt;even generates the SQL to drop them&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt;
  &lt;span class="n"&gt;table_name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;redundant_index_name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;     &lt;span class="c1"&gt;-- the redundant one (candidate to drop)&lt;/span&gt;
  &lt;span class="n"&gt;redundant_index_columns&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;dominant_index_name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;      &lt;span class="c1"&gt;-- the one that covers it (keep this)&lt;/span&gt;
  &lt;span class="n"&gt;dominant_index_columns&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;sql_drop_index&lt;/span&gt;            &lt;span class="c1"&gt;-- a DROP statement you can run as-is&lt;/span&gt;
&lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;sys&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;schema_redundant_indexes&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;table_name&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'logs'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Sample output:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;redundant_index_name &lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;idx_logs_on_import_id&lt;/span&gt;
&lt;span class="na"&gt;dominant_index_name  &lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;idx_logs_on_import_id_and_file&lt;/span&gt;
&lt;span class="na"&gt;sql_drop_index       &lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ALTER TABLE `app`.`logs` DROP INDEX `idx_logs_on_import_id`&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  2. &lt;code&gt;pt-duplicate-key-checker&lt;/code&gt; (Percona Toolkit / CLI)
&lt;/h3&gt;

&lt;p&gt;The go-to tool that scans the whole DB at once and spits out duplicate/redundant indexes along with DROP statements. Easy to plug into CI or a scheduled job.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;pt-duplicate-key-checker --host 127.0.0.1 --user &lt;span class="kd"&gt;readonly&lt;/span&gt; --ask-pass
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  3. &lt;code&gt;sys.schema_unused_indexes&lt;/code&gt; (finding unused indexes)
&lt;/h3&gt;

&lt;p&gt;On a different axis from "redundant," this lists indexes that "haven't been used by a single query since the server last started." But see the FK caveat below.&lt;/p&gt;

&lt;h3&gt;
  
  
  4. Tools that come with your ORM (e.g. Rails' &lt;code&gt;active_record_doctor&lt;/code&gt;)
&lt;/h3&gt;

&lt;p&gt;From the app side, you can detect &lt;code&gt;detect_extraneous_indexes&lt;/code&gt; (redundant) and &lt;code&gt;detect_unindexed_foreign_keys&lt;/code&gt; (FKs without an index). Since it runs in the same language as your migrations, it plays nicely with CI.&lt;/p&gt;




&lt;h2&gt;
  
  
  [Important] Redundant candidates you must NOT drop: foreign key (FK) indexes
&lt;/h2&gt;

&lt;p&gt;Even if a tool says "unused" or "candidate," &lt;strong&gt;some indexes will throw an error if you drop them&lt;/strong&gt;. Those are &lt;strong&gt;foreign key indexes&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Whenever a parent row is deleted or updated, MySQL checks every time whether any child rows still reference it. That's essentially a &lt;code&gt;WHERE fk_column = ?&lt;/code&gt; lookup, and &lt;strong&gt;without an index it's a full scan every time — painfully slow&lt;/strong&gt;. So MySQL requires that "if you add an FK, the child column must have an index," and creates one automatically if there isn't one.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- Even if this looks "unused," it's required for the FK. Dropping it gives ERROR 1553.&lt;/span&gt;
&lt;span class="k"&gt;KEY&lt;/span&gt; &lt;span class="sb"&gt;`fk_logs_on_user_id`&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`user_id`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="k"&gt;CONSTRAINT&lt;/span&gt; &lt;span class="sb"&gt;`fk_logs_on_user_id`&lt;/span&gt; &lt;span class="k"&gt;FOREIGN&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`user_id`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;REFERENCES&lt;/span&gt; &lt;span class="sb"&gt;`users`&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`id`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;How to tell&lt;/strong&gt;: is there &lt;em&gt;another&lt;/em&gt; index that has that FK column as its leftmost column?&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;If yes (e.g. a composite index whose leftmost column is the FK column) → that one satisfies the FK requirement, so the single-column index can go.&lt;/li&gt;
&lt;li&gt;If no → that index is the FK's only lifeline → &lt;strong&gt;you can't drop it&lt;/strong&gt; (dropping it gives &lt;code&gt;ERROR 1553: Cannot drop index ... needed in a foreign key constraint&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In the example at the top, the single &lt;code&gt;(import_id)&lt;/code&gt; can be dropped because the composite &lt;code&gt;(import_id, file_path)&lt;/code&gt; has &lt;code&gt;import_id&lt;/code&gt; as its leftmost column, so &lt;strong&gt;it can take over the FK index requirement too&lt;/strong&gt;.&lt;/p&gt;




&lt;h2&gt;
  
  
  How to remove them safely
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Migration
&lt;/h3&gt;

&lt;p&gt;It's just dropping one index. Keep it reversible (a rollback brings it back).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;RemoveRedundantIndexFromLogs&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nc"&gt;ActiveRecord&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nc"&gt;Migration&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mf"&gt;8.0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;change&lt;/span&gt;
    &lt;span class="n"&gt;remove_index&lt;/span&gt; &lt;span class="ss"&gt;:logs&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;column&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="ss"&gt;:import_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'idx_logs_on_import_id'&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In plain SQL:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;ALTER&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="sb"&gt;`logs`&lt;/span&gt; &lt;span class="k"&gt;DROP&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="sb"&gt;`idx_logs_on_import_id`&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Before applying, confirm for real that it can be dropped
&lt;/h3&gt;

&lt;p&gt;Especially for &lt;strong&gt;columns involved in an FK&lt;/strong&gt;, even if on paper you think "the composite should cover it," it's reassuring to actually run the DROP once and make sure &lt;code&gt;ERROR 1553&lt;/code&gt; doesn't show up. Run up → down on your dev DB and confirm you can roll it back, too.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Check that the DROP actually goes through (no FK error)&lt;/span&gt;
bin/rails db:migrate:up   &lt;span class="nv"&gt;VERSION&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;version&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="c"&gt;# Once confirmed, roll it back (keep the dev DB clean)&lt;/span&gt;
bin/rails db:migrate:down &lt;span class="nv"&gt;VERSION&lt;/span&gt;&lt;span class="o"&gt;=&amp;lt;&lt;/span&gt;version&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If &lt;code&gt;up&lt;/code&gt; goes through without &lt;code&gt;ERROR 1553&lt;/code&gt;, that's rock-solid proof that "the composite index satisfies the FK index requirement."&lt;/p&gt;

</description>
      <category>sql</category>
      <category>rails</category>
    </item>
    <item>
      <title>Building a Bulk Business Card Import with OCR — The “Multiple Cards per Page” Trap</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:41:28 +0000</pubDate>
      <link>https://dev.to/kaziusan/building-a-bulk-business-card-import-with-ocr-the-multiple-cards-per-page-trap-2kic</link>
      <guid>https://dev.to/kaziusan/building-a-bulk-business-card-import-with-ocr-the-multiple-cards-per-page-trap-2kic</guid>
      <description>&lt;h2&gt;
  
  
  Introduction
&lt;/h2&gt;

&lt;p&gt;Typing all those paper business cards you pile up at trade shows into a CRM by hand is a real chore. So at work, I built a feature where &lt;strong&gt;"you upload a PDF (or images) stuffed with business cards, and it automatically bulk-registers the company and contact data."&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;At first I thought, "Just throw it at OCR and we're done." But once I actually tried it, I realized that &lt;em&gt;OCR isn't as all-powerful as you'd think&lt;/em&gt;, and that the design decision of &lt;em&gt;where to split the processing&lt;/em&gt; is the real key. In this post I'll share those key points, plus the problem I agonized over the most: &lt;strong&gt;"What do we do when a single page has multiple business cards lined up on it?"&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The Overall Flow
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Upload a file (PDF / JPEG / PNG)&lt;/li&gt;
&lt;li&gt;Validate on the server side (format, size, page count)&lt;/li&gt;
&lt;li&gt;Create an "importing" history record and &lt;strong&gt;return a response right away&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;Run the heavy work (OCR → structuring → create/update) in a &lt;strong&gt;background job&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;The frontend polls the history ID and shows progress&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The point is to &lt;strong&gt;cleanly separate "accepting" from "the actual processing."&lt;/strong&gt; OCR and record matching can take anywhere from tens of seconds to several minutes, so if you try to do everything synchronously inside the request, it times out. The accepting API wraps up neatly at "save the file, create the history record, and kick off the job."&lt;/p&gt;

&lt;h2&gt;
  
  
  OCR Is a "Two-Step" Process
&lt;/h2&gt;

&lt;p&gt;Reading a business card actually splits into two different processes.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Reading the text (OCR)&lt;/strong&gt; … Extract strings from the image. This is the job of a general-purpose OCR like Google Cloud Vision.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Sorting into fields (structuring)&lt;/strong&gt; … Decide which parts of the extracted text are "the company name, the person's name, the phone number," and so on. This is the job of our own field extraction model.
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Card image → ① OCR (read all the text) → text → ② Structuring (sort into fields) → { company name, name, email... }
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It's easy to assume "OCR = does everything, including structuring," but &lt;strong&gt;① only outputs text and positions, and ② only organizes that into fields&lt;/strong&gt;. They're separate roles.&lt;/p&gt;

&lt;h2&gt;
  
  
  Design Points That Paid Off
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Validate based on the "contents."&lt;/strong&gt;&lt;br&gt;
If you check "is this a PDF?" by file extension or Content-Type, someone can get past it just by renaming an image to &lt;code&gt;.pdf&lt;/code&gt;. It's safer to determine the real type from the &lt;strong&gt;magic bytes at the start of the file&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Don't load big files into memory.&lt;/strong&gt;&lt;br&gt;
A file with 100 business cards gets big. When sending it to storage (S3, etc.), &lt;strong&gt;stream it straight through without reading the whole thing into memory&lt;/strong&gt;. The size check also looks only at metadata, not the contents.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Check the PDF page count with a lightweight read.&lt;/strong&gt;&lt;br&gt;
If all you want is to reject "more than N pages" at upload time, an image rendering library (ImageMagick, etc.) is way too heavy. &lt;strong&gt;Counting pages doesn't need rendering&lt;/strong&gt;; reading the metadata with a lightweight PDF parser is plenty.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Problem I Agonized Over Most: "Multiple Cards on One Page"
&lt;/h2&gt;

&lt;p&gt;While nailing down the requirements, this case came up: &lt;strong&gt;multiple business cards lined up in a single scanned image (one page of a PDF)&lt;/strong&gt;. If you scan several cards at once on a copier or flatbed scanner, that's naturally what you get.&lt;/p&gt;

&lt;h3&gt;
  
  
  OCR doesn't split things "per card"
&lt;/h3&gt;

&lt;p&gt;This was my blind spot. A general-purpose OCR (Vision, etc.) returns "all the text on the page + the position coordinates of each piece of text," but &lt;strong&gt;it has no feature to logically separate "which text belongs to which card"&lt;/strong&gt; (Google Cloud Vision's official docs also clearly state that there's no built-in feature for identifying and separating multiple documents on one page, and that you need your own logic that analyzes block positions).&lt;/p&gt;

&lt;p&gt;On top of that, OCR "blocks" (chunks of text) are grouped by &lt;em&gt;layout proximity&lt;/em&gt;, so &lt;strong&gt;neighboring cards get merged into one, or a single card gets split into several&lt;/strong&gt;. "1 block = 1 card" just doesn't hold.&lt;/p&gt;

&lt;p&gt;The structuring model also assumes it's sorting "the text of one business card," so if you pass it text from multiple cards mixed together, you end up with &lt;strong&gt;bogus data that merges "Company A's name + Mr. B's name."&lt;/strong&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  So we need to add our own "split per card" step
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;OCR (all text + coordinates) → [our own] split per card → Card A part → structuring
                                                      → Card B part → structuring → …
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;How hard this splitting is depends heavily on &lt;strong&gt;how the cards are arranged&lt;/strong&gt;.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Arrangement&lt;/th&gt;
&lt;th&gt;Approach&lt;/th&gt;
&lt;th&gt;Difficulty&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Fixed template (always 2×3, etc.)&lt;/td&gt;
&lt;td&gt;Divide the page into fixed equal parts&lt;/td&gt;
&lt;td&gt;Low (but every user is forced into the same arrangement)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Neatly arranged, but variable count&lt;/td&gt;
&lt;td&gt;Dynamically detect rows/columns from "gaps" in the coordinates&lt;/td&gt;
&lt;td&gt;Medium (rule-based; weak against tilt, cards touching, empty cells)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Completely random&lt;/td&gt;
&lt;td&gt;Prepare an AI model that detects card regions&lt;/td&gt;
&lt;td&gt;High (requires training and operating a model)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The middle option, "infer the grid from coordinates," is a rule-based process that looks something like this:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Collect the coordinates of all the text&lt;/li&gt;
&lt;li&gt;Treat &lt;strong&gt;large gaps&lt;/strong&gt; in the X coordinates as "column boundaries"&lt;/li&gt;
&lt;li&gt;Treat &lt;strong&gt;large gaps&lt;/strong&gt; in the Y coordinates as "row boundaries"&lt;/li&gt;
&lt;li&gt;Treat each cell as one card and group the text accordingly&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Since it's geometry rather than AI, it's relatively lightweight, but it falls apart with &lt;strong&gt;tilt, cards touching each other, uneven sizes, and empty cells&lt;/strong&gt;. The more robust you try to make it, the more tuning on real data you need, and if you push it all the way, you end up drifting toward "just detect the cards themselves with AI."&lt;/p&gt;

&lt;h3&gt;
  
  
  Lesson: if you can add "constraints" on the spec side, things get way easier
&lt;/h3&gt;

&lt;p&gt;Rather than forcing tech to handle randomly placed cards, &lt;strong&gt;setting input constraints like "please scan the cards evenly spaced"&lt;/strong&gt; cuts both development cost and accuracy risk dramatically. "How much input do we accept?" shouldn't be decided by engineers alone; it's something we should have aligned on with the product side early.&lt;/p&gt;

&lt;h2&gt;
  
  
  Handling Duplicate Data (Record Matching)
&lt;/h2&gt;

&lt;p&gt;With bulk registration, duplicates with "companies/contacts that are already registered" are unavoidable. Here we have the user choose in advance:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Companies&lt;/strong&gt; are matched by "company name" or "company name + address" (address is an option because some people want to distinguish branch offices)&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Contacts&lt;/strong&gt; are matched by email address&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Matches are treated as updates, and non-matches as new records. We also let the user choose "whether to overwrite existing data with the card's values on a duplicate" (because some people don't want their data overwritten without asking).&lt;/p&gt;

&lt;h2&gt;
  
  
  Summary
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;OCR is a two-step process: "read the text" + "sort into fields." &lt;strong&gt;OCR alone doesn't get you all the way to structured data.&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;Separate accepting from the actual processing, and send heavy work to async jobs. Stream large files, and validate by contents.&lt;/li&gt;
&lt;li&gt;The biggest trap is &lt;strong&gt;"multiple cards per page."&lt;/strong&gt; OCR won't split by card, so you have to implement the splitting yourself, and &lt;strong&gt;the difficulty changes drastically depending on the arrangement&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;That's exactly why &lt;strong&gt;agreeing with the product side on "how much we can constrain the input"&lt;/strong&gt; is just as important as choosing the technology.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It was a great example of how the features that look like "just throw it at OCR" are actually the ones where designing the requirements and constraints matters most.&lt;/p&gt;

&lt;h2&gt;
  
  
  (Epilogue)
&lt;/h2&gt;

&lt;p&gt;After all that groaning over "how do we split it if there are multiple cards on a page…", I checked with the product side and—&lt;/p&gt;

&lt;p&gt;"We're assuming one business card per PDF page."&lt;/p&gt;

&lt;p&gt;…Yep. A whole lot of worrying over nothing. lol&lt;/p&gt;

&lt;p&gt;Still, I learned a lot. Before you throw tech at a problem, question the requirements first. A fine lesson, if I do say so myself.&lt;/p&gt;

</description>
      <category>ocr</category>
      <category>rails</category>
    </item>
    <item>
      <title>What Is Rails' structure.sql? What's It For?</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:40:36 +0000</pubDate>
      <link>https://dev.to/kaziusan/what-is-rails-structuresql-whats-it-for-22d8</link>
      <guid>https://dev.to/kaziusan/what-is-rails-structuresql-whats-it-for-22d8</guid>
      <description>&lt;p&gt;When you work on a Rails project, you'll come across a huge file called &lt;code&gt;db/structure.sql&lt;/code&gt;.&lt;br&gt;
"What is this? It changes on its own, so am I allowed to touch it?" It's an easy file to be confused by, so here's a beginner-friendly rundown.&lt;/p&gt;


&lt;h2&gt;
  
  
  Bottom line: the DB's "finished blueprint"
&lt;/h2&gt;

&lt;p&gt;In a nutshell, &lt;code&gt;structure.sql&lt;/code&gt; is&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;a "finished blueprint (snapshot)" that bundles the SQL statements needed to recreate the current database structure entirely from scratch&lt;/strong&gt;&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;What's more, it's a file that &lt;strong&gt;Rails generates and updates automatically&lt;/strong&gt;; it's not something people write by hand.&lt;/p&gt;

&lt;p&gt;Here's roughly what's inside:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="sb"&gt;`deals`&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;              &lt;span class="c1"&gt;-- Statement that creates the "deals" table&lt;/span&gt;
  &lt;span class="sb"&gt;`id`&lt;/span&gt; &lt;span class="kt"&gt;bigint&lt;/span&gt; &lt;span class="n"&gt;unsigned&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="kc"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="sb"&gt;`name`&lt;/span&gt; &lt;span class="kt"&gt;varchar&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;255&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="sb"&gt;`contacts`&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;    &lt;span class="c1"&gt;-- Statement that creates the "contacts" table&lt;/span&gt;
&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;continues&lt;/span&gt; &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;every&lt;/span&gt; &lt;span class="k"&gt;table&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;

&lt;span class="c1"&gt;-- At the end, a ledger of "which schema changes have been applied so far"&lt;/span&gt;
&lt;span class="k"&gt;INSERT&lt;/span&gt; &lt;span class="k"&gt;INTO&lt;/span&gt; &lt;span class="sb"&gt;`schema_migrations`&lt;/span&gt; &lt;span class="k"&gt;VALUES&lt;/span&gt;
&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'20260806000000'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'20260805000000'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first part has &lt;code&gt;CREATE TABLE&lt;/code&gt; for every table, and the end has a ledger (&lt;code&gt;schema_migrations&lt;/code&gt;) of "how far the changes have been applied."&lt;/p&gt;




&lt;h2&gt;
  
  
  Background: how it relates to migrations
&lt;/h2&gt;

&lt;p&gt;The shortcut to understanding &lt;code&gt;structure.sql&lt;/code&gt; is to think about it together with &lt;strong&gt;migrations&lt;/strong&gt;.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Migrations&lt;/strong&gt; = the &lt;strong&gt;change history&lt;/strong&gt; of the DB structure (= a stack of instructions for schema changes)

&lt;ul&gt;
&lt;li&gt;e.g. a file like "add a status column to the deals table," one file per change&lt;/li&gt;
&lt;li&gt;File names are &lt;strong&gt;date + number&lt;/strong&gt;, like &lt;code&gt;20260803000000&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;structure.sql&lt;/strong&gt; = &lt;strong&gt;a snapshot of the final result after applying that entire history&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;As a diagram:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;① A developer writes a migration file (instructions for the change)
         e.g. "add a status column to deals"

② Run db:migrate → the DB actually changes

③ ★At this point, Rails automatically updates structure.sql to "what the DB looks like now"★
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In other words, &lt;code&gt;structure.sql&lt;/code&gt; is &lt;strong&gt;automatically updated as a by-product&lt;/strong&gt; of &lt;code&gt;db:migrate&lt;/code&gt;. As a rule, you don't edit it by hand.&lt;/p&gt;




&lt;h2&gt;
  
  
  What's it for?
&lt;/h2&gt;

&lt;p&gt;The biggest reason it exists is that &lt;strong&gt;it's fast when you build a new DB from scratch&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;When a new team member sets up their environment, or when you rebuild the test DB every time, you need to take the DB from "blank → latest shape." There are two ways to do that.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Method&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;th&gt;Speed&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Run all the migrations&lt;/td&gt;
&lt;td&gt;Runs hundreds of instruction files one by one, in order&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Slow&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Load &lt;code&gt;structure.sql&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Recreates the finished shape in one shot&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Fast&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  Why is running all the migrations slow?
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Reason ①: It retraces history, so there's a lot of waste&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Migrations are a change history, so running all of them recreates every past detour too.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;① Create the deals table
② Add a status column to deals
③ Remove the status column from ②   ← changed our minds
④ Add a state column to deals
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;All we actually want in the end is "no status, but a state column." But running everything &lt;strong&gt;faithfully recreates even the pointless round trip&lt;/strong&gt; of creating it in ② and deleting it in ③. &lt;code&gt;structure.sql&lt;/code&gt; only has the final result, so there are no detours.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Reason ②: They can only run one at a time, in sequence (overhead)&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Migrations depend on order, so they can't be parallelized, and each one involves setup and teardown: "boot Rails → load code → convert to SQL → execute → record in the ledger." That piles up hundreds of times.&lt;br&gt;
&lt;code&gt;structure.sql&lt;/code&gt; just pours in one giant SQL file, so this repeated cost is nearly zero.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Reason ③: Rebuilding intermediate states adds up&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Even for the same "add a state column," migrations rebuild intermediate states over and over: create table → add column → remove column → add a different column… It gets even slower when things like rebuilding indexes are involved.&lt;/p&gt;

&lt;h3&gt;
  
  
  An analogy
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;Running all migrations = &lt;strong&gt;watching a cooking show from episode 1&lt;/strong&gt;, and recreating even the failed dishes along the way&lt;/li&gt;
&lt;li&gt;structure.sql = looking at &lt;strong&gt;a photo and recipe of the finished dish&lt;/strong&gt; and making just that&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;All you want is the finished dish, so the latter is way faster.&lt;/p&gt;




&lt;h2&gt;
  
  
  So you use them for different things
&lt;/h2&gt;

&lt;p&gt;Neither &lt;code&gt;structure.sql&lt;/code&gt; nor migrations is "better"; &lt;strong&gt;you use each one depending on the situation&lt;/strong&gt;.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Situation&lt;/th&gt;
&lt;th&gt;What to use&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Setting up a new environment, creating the test DB&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;structure.sql&lt;/strong&gt; (finished shape)&lt;/td&gt;
&lt;td&gt;No need to retrace history; you just want the latest state fast&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Changing the live production DB&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Migrations&lt;/strong&gt; (only the diff)&lt;/td&gt;
&lt;td&gt;You want to safely apply just "this change" while keeping existing data&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A new member's environment setup is just "go from blank → latest shape," so &lt;code&gt;structure.sql&lt;/code&gt; is the perfect fit.&lt;/p&gt;




&lt;h2&gt;
  
  
  Extra: schema.rb vs. structure.sql
&lt;/h2&gt;

&lt;p&gt;Rails blueprints come in two formats, and each project picks one.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;File&lt;/th&gt;
&lt;th&gt;Contents&lt;/th&gt;
&lt;th&gt;Characteristics&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;db/schema.rb&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A blueprint written in Ruby&lt;/td&gt;
&lt;td&gt;Simple. The Rails default&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;db/structure.sql&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A blueprint written in raw SQL&lt;/td&gt;
&lt;td&gt;Can faithfully express even triggers and DB-specific features&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Projects that use features the Ruby &lt;code&gt;schema.rb&lt;/code&gt; can't fully express, like MySQL triggers or detailed constraints, choose &lt;code&gt;structure.sql&lt;/code&gt;.&lt;/p&gt;




&lt;h2&gt;
  
  
  Summary
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Question&lt;/th&gt;
&lt;th&gt;Answer&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;What is structure.sql?&lt;/td&gt;
&lt;td&gt;A "finished blueprint" that bundles the SQL to recreate the whole current DB structure&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Does Rails create it?&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Yes&lt;/strong&gt;. It's automatically generated/updated when you run &lt;code&gt;db:migrate&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Do you write it by hand?&lt;/td&gt;
&lt;td&gt;As a rule, no. It's updated automatically&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;What's it good for?&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Instantly getting&lt;/strong&gt; a new environment or test DB &lt;strong&gt;to the latest structure&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

</description>
      <category>rails</category>
      <category>sql</category>
    </item>
    <item>
      <title>Understanding Rack, Processes, Threads, Unicorn, Puma, and Action Cable Through a Restaurant</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:40:25 +0000</pubDate>
      <link>https://dev.to/kaziusan/understanding-rack-processes-threads-unicorn-puma-and-action-cable-through-a-restaurant-1e44</link>
      <guid>https://dev.to/kaziusan/understanding-rack-processes-threads-unicorn-puma-and-action-cable-through-a-restaurant-1e44</guid>
      <description>&lt;p&gt;When you're just writing Controllers and Models day to day, you don't really think about what's running underneath Rails.&lt;br&gt;
But &lt;strong&gt;the moment you try to add an "always-connected" feature like real-time chat or notifications to a Rails app&lt;/strong&gt;, suddenly people start saying things like "Unicorn doesn't play well with that" or "Action Cable handles it fine."&lt;/p&gt;

&lt;p&gt;In this post, I'll lay out the machinery under Rails that you need to make sense of those conversations, using a &lt;strong&gt;restaurant&lt;/strong&gt; as the analogy.&lt;/p&gt;


&lt;h2&gt;
  
  
  1. Rack: the standard order ticket format
&lt;/h2&gt;

&lt;p&gt;Rack is &lt;strong&gt;the common agreement that connects Ruby web servers and web apps&lt;/strong&gt;.&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Any object that has &lt;code&gt;call(env)&lt;/code&gt; and returns &lt;code&gt;[status, headers, body]&lt;/code&gt; is a Rack app&lt;br&gt;
&lt;/p&gt;


&lt;/blockquote&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;HelloApp&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;call&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;200&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s1"&gt;'content-type'&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s1"&gt;'text/plain'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'Hello'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In restaurant terms, it's &lt;strong&gt;the order ticket format&lt;/strong&gt;. Because the format is fixed, you can freely mix and match the dining floor (Unicorn, Puma) and the kitchen (Rails, Sinatra).&lt;/p&gt;

&lt;p&gt;Before an order ticket reaches the kitchen, it passes through &lt;strong&gt;middleware&lt;/strong&gt; (the security guard and the front desk at the entrance).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Customer → Security guard (Rack::Attack) → Front desk (Rack::Cors) → Kitchen (Rails)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  2. Layers: dining floor → front desk → kitchen
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Web server (Unicorn / Puma)       Dining floor: greets customers and assigns staff
Rack + middleware                 Order tickets, plus the front desk and security
Application layer (Rails)         Kitchen: where Controllers and Models run
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The "application layer" here is not the one from the OSI reference model. It just means &lt;strong&gt;the stage where your Rails code runs&lt;/strong&gt;.&lt;/p&gt;




&lt;h2&gt;
  
  
  3. Processes and threads: restaurants and staff
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Process = a restaurant (has its own kitchen and fridge)
Thread  = a staff member (shares the fridge within the same restaurant)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Process (restaurant)&lt;/th&gt;
&lt;th&gt;Thread (staff member)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Memory&lt;/td&gt;
&lt;td&gt;Separate&lt;/td&gt;
&lt;td&gt;Shared&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cost to create&lt;/td&gt;
&lt;td&gt;Heavy&lt;/td&gt;
&lt;td&gt;Light&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The scary part&lt;/td&gt;
&lt;td&gt;Eats memory&lt;/td&gt;
&lt;td&gt;Fighting over shared data&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;
&lt;span class="nc"&gt;Thread&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;new&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;join&lt;/span&gt;
&lt;span class="nb"&gt;p&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;  &lt;span class="c1"&gt;# =&amp;gt; 100 (shared, so it gets overwritten)&lt;/span&gt;

&lt;span class="n"&gt;y&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;
&lt;span class="nc"&gt;Process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;wait&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;fork&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;y&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;100&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nb"&gt;p&lt;/span&gt; &lt;span class="n"&gt;y&lt;/span&gt;  &lt;span class="c1"&gt;# =&amp;gt; 0 (a different restaurant, so no effect)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When staff share a fridge, you get accidents like "two people count the eggs at the same time and the inventory count ends up wrong." That's the &lt;strong&gt;thread-safety problem&lt;/strong&gt;. In Ruby, class variables and global variables are that "shared fridge."&lt;/p&gt;




&lt;h2&gt;
  
  
  4. Blocking: a staff member stuck standing by the table
&lt;/h2&gt;

&lt;p&gt;When a thread is waiting on something and can't do anything else in the meantime, that's called &lt;strong&gt;blocking&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Staff: "What can I get you?"
Customer: (staring at the menu for 30 minutes...)
Staff: (just standing there by the table the whole time)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For normal requests the wait is a split second, so it's no big deal. The trouble starts with &lt;strong&gt;"always-connected" communication like long polling or WebSockets&lt;/strong&gt;.&lt;/p&gt;




&lt;h2&gt;
  
  
  5. Unicorn: open lots of one-person restaurants
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Unicorn master (owner)
 ├ Worker 1 (one staff member)
 ├ Worker 2 (one staff member)
 └ Worker 3 (one staff member)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;Each worker can only handle one request at a time&lt;/li&gt;
&lt;li&gt;Each restaurant is independent, so it's safe. But it eats memory&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;When always-connected traffic shows up, this happens:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Workers 1–3: all standing by a customer's table
→ Nobody's free to serve the next customer 💀
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  6. Puma: put lots of staff in one restaurant
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Puma process
 ├ Thread 1 (staff)
 ├ Thread 2 (staff)
 └ Thread 3 (staff)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;Handles more customers with less memory than Unicorn&lt;/li&gt;
&lt;li&gt;Your code needs to be thread-safe&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Ruby has the &lt;strong&gt;GVL&lt;/strong&gt;, which means only one thread can run Ruby code at a time (picture a kitchen with just one knife). Still, a thread lets go of the knife while it waits on the DB and such, so for web apps it's plenty fast.&lt;/p&gt;

&lt;p&gt;But with always-connected traffic, the threads all get tied up waiting, and you end up jammed just like with Unicorn.&lt;/p&gt;




&lt;h2&gt;
  
  
  7. Action Cable: a floor attendant making rounds with call bells
&lt;/h2&gt;

&lt;p&gt;(Runs on top of Rails)&lt;/p&gt;

&lt;p&gt;Here we flip the idea: &lt;strong&gt;stop waiting by the table.&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Floor attendant (just one):
  Puts a call bell on every table
  → Only goes over to the tables whose bell rings, and handles them quickly
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is an &lt;strong&gt;event loop&lt;/strong&gt;. Since nobody is glued to idle connections, it can handle a huge number of them.&lt;/p&gt;

&lt;p&gt;Action Cable uses Rack's &lt;code&gt;rack.hijack&lt;/code&gt; to take over the connection itself and hand it to this event loop. That frees up the web server's worker right away, so &lt;strong&gt;it even works on top of Unicorn&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Weakness&lt;/strong&gt;: if the floor attendant gets absorbed in one heavy task, every table has to wait.&lt;br&gt;
→ On Action Cable, avoid heavy queries and &lt;code&gt;sleep&lt;/code&gt;, and hand heavy work off to background jobs.&lt;/p&gt;




&lt;h2&gt;
  
  
  Summary
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;What gets stuck on idle connections&lt;/th&gt;
&lt;th&gt;As connections grow&lt;/th&gt;
&lt;th&gt;Heavy work&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Unicorn&lt;/td&gt;
&lt;td&gt;Processes&lt;/td&gt;
&lt;td&gt;Runs out of memory&lt;/td&gt;
&lt;td&gt;Strong&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Puma&lt;/td&gt;
&lt;td&gt;Threads&lt;/td&gt;
&lt;td&gt;Runs out of threads&lt;/td&gt;
&lt;td&gt;Decent&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Action Cable&lt;/td&gt;
&lt;td&gt;Nothing&lt;/td&gt;
&lt;td&gt;Mostly fine&lt;/td&gt;
&lt;td&gt;Weak&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

</description>
      <category>infrastructure</category>
      <category>rails</category>
    </item>
    <item>
      <title>Ruby Blocks and yield Explained with the Simplest Examples</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:40:04 +0000</pubDate>
      <link>https://dev.to/kaziusan/ruby-blocks-and-yield-explained-with-the-simplest-examples-42j2</link>
      <guid>https://dev.to/kaziusan/ruby-blocks-and-yield-explained-with-the-simplest-examples-42j2</guid>
      <description>&lt;p&gt;If you write Ruby, you'll always run into "blocks" and "yield."&lt;br&gt;
They look tricky, but really it's just &lt;strong&gt;"passing some code" and "running the code you were passed."&lt;/strong&gt;&lt;/p&gt;
&lt;h2&gt;
  
  
  What's a block?
&lt;/h2&gt;

&lt;p&gt;It's &lt;strong&gt;a "chunk of code (a little snippet)" you pass to a method&lt;/strong&gt;.&lt;br&gt;
You wrap it in &lt;code&gt;{ }&lt;/code&gt; or &lt;code&gt;do...end&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;each&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="n"&gt;n&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="c1"&gt;#              └──────────┘ this is the block&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You're handing &lt;code&gt;.each&lt;/code&gt; a set of &lt;strong&gt;instructions&lt;/strong&gt; saying "do &lt;code&gt;puts n&lt;/code&gt; for each element."&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;1
2
3
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;{ }&lt;/code&gt; and &lt;code&gt;do...end&lt;/code&gt; are the same thing. You just use &lt;code&gt;do...end&lt;/code&gt; when it gets long.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;3&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;each&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;
  &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="n"&gt;n&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  What's yield?
&lt;/h2&gt;

&lt;p&gt;It's &lt;strong&gt;an instruction that runs the passed-in block at "the spot where you wrote yield" inside the method&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;greet&lt;/span&gt;
  &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="s2"&gt;"Hello"&lt;/span&gt;
  &lt;span class="k"&gt;yield&lt;/span&gt;              &lt;span class="c1"&gt;# ← run the passed-in block here&lt;/span&gt;
  &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="s2"&gt;"Goodbye"&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;

&lt;span class="n"&gt;greet&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="s2"&gt;"How are you?"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Hello
How are you?    ← the block gets inserted where yield is
Goodbye
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You can &lt;strong&gt;put yield anywhere, call it as many times as you like, and even pass values to it&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;count_up&lt;/span&gt;
  &lt;span class="k"&gt;yield&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
  &lt;span class="k"&gt;yield&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;

&lt;span class="n"&gt;count_up&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;n&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="s2"&gt;"Item #{n}"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="c1"&gt;# Item 1&lt;/span&gt;
&lt;span class="c1"&gt;# Item 2&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How the two relate
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Block&lt;/strong&gt; = the "to-do note" you pass (written by the caller)&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;yield&lt;/strong&gt; = the instruction that runs that note (written by the method)&lt;/li&gt;
&lt;/ul&gt;

&lt;blockquote&gt;
&lt;p&gt;The method decides &lt;strong&gt;where&lt;/strong&gt; it gets inserted; the caller decides &lt;strong&gt;what&lt;/strong&gt; gets inserted.&lt;/p&gt;
&lt;/blockquote&gt;




&lt;h2&gt;
  
  
  In practice: "wrapping" code with yield
&lt;/h2&gt;

&lt;p&gt;The really handy use of yield is the pattern of &lt;strong&gt;wrapping the passed-in code with shared setup and cleanup&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;with_debug&lt;/span&gt;
  &lt;span class="n"&gt;old&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Rails&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;level&lt;/span&gt;
  &lt;span class="nc"&gt;Rails&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;level&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="ss"&gt;:debug&lt;/span&gt;   &lt;span class="c1"&gt;# Setup: switch logging to debug&lt;/span&gt;
  &lt;span class="k"&gt;yield&lt;/span&gt;                         &lt;span class="c1"&gt;# Run the caller's code&lt;/span&gt;
&lt;span class="k"&gt;ensure&lt;/span&gt; &lt;span class="c1"&gt;# Always runs at the end, whether an error happens or not (= finally)&lt;/span&gt;
  &lt;span class="nc"&gt;Rails&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;level&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;old&lt;/span&gt;      &lt;span class="c1"&gt;# Cleanup: always restore it&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Usage:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;with_debug&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="c1"&gt;# Logging is debug only inside here&lt;/span&gt;
  &lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;save!&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="c1"&gt;# Once you leave this, the log level is automatically restored&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Why it's handy
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You can keep the shared part (switching and restoring the log level) in one place&lt;/strong&gt;. The caller only has to write "what they want to do."&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;ensure&lt;/code&gt; guarantees the cleanup&lt;/strong&gt;. Even if an error happens inside the block, the log level always gets restored.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Without yield, you'd be stuck copy-pasting "switch → do the work → restore" every single place you use it. With yield, you can split things cleanly: &lt;strong&gt;the frame (setup/cleanup) lives in the method, the contents come from the caller&lt;/strong&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Another example: measuring execution time
&lt;/h3&gt;

&lt;p&gt;You can write "measure execution time" with the same pattern.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;measure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;label&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;start&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Time&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;now&lt;/span&gt;
  &lt;span class="k"&gt;yield&lt;/span&gt;
&lt;span class="k"&gt;ensure&lt;/span&gt;
  &lt;span class="nb"&gt;puts&lt;/span&gt; &lt;span class="s2"&gt;"#{label}: #{Time.now - start} sec"&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;

&lt;span class="nf"&gt;measure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Heavy task"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;heavy_task&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="c1"&gt;# =&amp;gt; Heavy task: 1.23 sec&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;"Wrap a block with shared setup and cleanup"&lt;/strong&gt; — this is a super common design pattern in Ruby.&lt;br&gt;
Things like &lt;code&gt;File.open { |f| ... }&lt;/code&gt; (open it and always close it) belong to the same family.&lt;/p&gt;

</description>
      <category>beginners</category>
      <category>coding</category>
      <category>ruby</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>Indexing Calculated Results from Multiple SQL Columns, and the Limits of Write Overhead</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:39:53 +0000</pubDate>
      <link>https://dev.to/kaziusan/indexing-calculated-results-from-multiple-sql-columns-and-the-limits-of-write-overhead-1e41</link>
      <guid>https://dev.to/kaziusan/indexing-calculated-results-from-multiple-sql-columns-and-the-limits-of-write-overhead-1e41</guid>
      <description>&lt;p&gt;When you run a search in a database that combines multiple columns (e.g. &lt;code&gt;(unit price × quantity - discount) × tax rate&lt;/code&gt;), it usually triggers a full scan (Table Scan) and causes major slowdowns.&lt;/p&gt;

&lt;p&gt;In this post, I'll explain how to roll the calculated result of multiple columns into a single or composite index, along with how big the write overhead (latency risk) you're probably worried about actually gets, and what to do when you need to be careful.&lt;/p&gt;




&lt;h2&gt;
  
  
  1. Two ways to put the calculated result of multiple columns into an index
&lt;/h2&gt;

&lt;p&gt;For example, consider an &lt;code&gt;orders&lt;/code&gt; table with these 5 columns:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;price&lt;/code&gt; (unit price)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;quantity&lt;/code&gt; (quantity)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;discount&lt;/code&gt; (discount)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;tax_rate&lt;/code&gt; (tax rate)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;status&lt;/code&gt; (order status)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you want to quickly find "completed orders with a total billed amount of 10,000 yen or more," there are 2 approaches.&lt;/p&gt;

&lt;h3&gt;
  
  
  Approach A: Create an expression index directly
&lt;/h3&gt;

&lt;p&gt;Define the formula itself in the index, and create a composite index that combines it with the &lt;code&gt;status&lt;/code&gt; column.&lt;/p&gt;

&lt;h4&gt;
  
  
  SQL (PostgreSQL)
&lt;/h4&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;idx_orders_total_amount_and_status&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;orders&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;price&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="n"&gt;quantity&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; &lt;span class="n"&gt;discount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="n"&gt;tax_rate&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; 
  &lt;span class="n"&gt;status&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h4&gt;
  
  
  Rails migration
&lt;/h4&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;AddCalculatedIndexToOrders&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nc"&gt;ActiveRecord&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nc"&gt;Migration&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mf"&gt;7.0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;change&lt;/span&gt;
    &lt;span class="n"&gt;add_index&lt;/span&gt; &lt;span class="ss"&gt;:orders&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; 
              &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"((price * quantity - discount) * (1 + tax_rate))"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="ss"&gt;:status&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
              &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"idx_orders_total_amount_and_status"&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Approach B: Generated column + composite index [Recommended]
&lt;/h3&gt;

&lt;p&gt;When the formula is complex, defining a "calculated result column" on the table and indexing that makes your SQL far more readable and maintainable.&lt;/p&gt;

&lt;h4&gt;
  
  
  Rails (Migration)
&lt;/h4&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;AddTotalAmountToOrders&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nc"&gt;ActiveRecord&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nc"&gt;Migration&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mf"&gt;7.0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;change&lt;/span&gt;
    &lt;span class="n"&gt;change_table&lt;/span&gt; &lt;span class="ss"&gt;:orders&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;
      &lt;span class="c1"&gt;# 1. Define a calculated column using the 4 columns (automatically computed &amp;amp; stored by the DB)&lt;/span&gt;
      &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;virtual&lt;/span&gt; &lt;span class="ss"&gt;:total_amount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; 
                &lt;span class="n"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="ss"&gt;:decimal&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; 
                &lt;span class="n"&gt;precision&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; 
                &lt;span class="n"&gt;scale&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; 
                &lt;span class="n"&gt;as&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"(price * quantity - discount) * (1 + tax_rate)"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; 
                &lt;span class="n"&gt;stored&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;

      &lt;span class="c1"&gt;# 2. Create a composite index on the generated column and status&lt;/span&gt;
      &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;index&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="ss"&gt;:total_amount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="ss"&gt;:status&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"idx_orders_total_amount_and_status"&lt;/span&gt;
    &lt;span class="k"&gt;end&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  2. How big the write (INSERT / UPDATE) overhead gets
&lt;/h2&gt;

&lt;p&gt;When you use a calculated index or a generated column, every time even one of the target columns is INSERTed or UPDATEd, a "recalculation + B-Tree index reshuffle" happens.&lt;/p&gt;

&lt;p&gt;The performance impact depends less on "the number of rows" and more on "the number of writes/updates per second (TPS)."&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Alert level&lt;/th&gt;
&lt;th&gt;Writes/updates per second (TPS)&lt;/th&gt;
&lt;th&gt;Impact on the app, assessment, recommended action&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Level 1: Safe&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Up to ~50/sec&lt;/td&gt;
&lt;td&gt;Typical web systems and e-commerce sites. Finishes in under a millisecond.&lt;br&gt;&lt;strong&gt;No action needed (go ahead and use it)&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Level 2: Caution&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;100–500/sec&lt;/td&gt;
&lt;td&gt;Traffic spikes and social media apps. Write latency rises slightly.&lt;br&gt;&lt;strong&gt;Keep monitoring (watch the slow query log)&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Level 3: Warning&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;1,000+/sec&lt;/td&gt;
&lt;td&gt;IoT data ingestion, financial transactions, heavy batch processing. CPU usage spikes and lock contention occurs.&lt;br&gt;&lt;strong&gt;Action required (the architecture needs rethinking)&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h4&gt;
  
  
  At what "data volume" does the impact get big?
&lt;/h4&gt;

&lt;p&gt;As data grows, performance drops sharply at "the point where the index itself no longer fits in memory (RAM)."&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;Size that fits in memory (up to a few million rows):&lt;br&gt;
All index updates complete in memory (RAM), so even with the calculation overhead, they finish in under a millisecond (a few milliseconds).&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;Size that doesn't fit in memory (tens of millions to hundreds of millions of rows):&lt;br&gt;
Every index update causes reads/writes to disk (SSD/HDD). At that point, the latency of a single UPDATE jumps from a few milliseconds to anywhere from a few milliseconds to several seconds.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h4&gt;
  
  
  "Worst case" patterns that tend to be especially slow
&lt;/h4&gt;

&lt;p&gt;Even for the same writes, the following patterns have especially large overhead.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;p&gt;It includes columns that are updated super frequently (e.g. updated_at or status)&lt;br&gt;
Amounts like price rarely change once they're set, but if status or updated_at is in the formula, every status change triggers a recalculation &amp;amp; index reshuffle.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;&lt;p&gt;You do bulk updates (UPDATE ... WHERE or BULK INSERT)&lt;br&gt;
Updating one row at a time only costs a few milliseconds of latency, but when you bulk-update 100,000 rows like UPDATE orders SET price = price * 1.1, 100,000 recalculations and index updates run at once, and the DB freezes for anywhere from a few seconds to a few minutes.&lt;/p&gt;&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>sql</category>
      <category>rails</category>
    </item>
    <item>
      <title>ActiveJob Too? Sure, Let's Explain Jobs, Queues, and Adapters with a Restaurant Again</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:39:32 +0000</pubDate>
      <link>https://dev.to/kaziusan/activejob-too-sure-lets-explain-jobs-queues-and-adapters-with-a-restaurant-again-d23</link>
      <guid>https://dev.to/kaziusan/activejob-too-sure-lets-explain-jobs-queues-and-adapters-with-a-restaurant-again-d23</guid>
      <description>&lt;p&gt;Yeah, I know, I know. But let me compare it to a restaurant anyway.&lt;/p&gt;




&lt;h2&gt;
  
  
  The cast
&lt;/h2&gt;

&lt;p&gt;First, a mapping table. I'll stick with this analogy for the whole post.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Rails term&lt;/th&gt;
&lt;th&gt;In restaurant terms&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Web request&lt;/td&gt;
&lt;td&gt;An order from a customer who walked in&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Controller&lt;/td&gt;
&lt;td&gt;Cashier&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Job&lt;/td&gt;
&lt;td&gt;Order ticket&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;perform_later&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Pinning the order ticket to the board&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Queue&lt;/td&gt;
&lt;td&gt;The board where order tickets are pinned&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Worker&lt;/td&gt;
&lt;td&gt;Cook&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Adapter&lt;/td&gt;
&lt;td&gt;The type of board&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;




&lt;h2&gt;
  
  
  Why do things "later" at all?
&lt;/h2&gt;

&lt;p&gt;Say we have a feature that sends a welcome email when a user signs up.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;UsersController&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nc"&gt;ApplicationController&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;create&lt;/span&gt;
    &lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;User&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user_params&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nc"&gt;WelcomeMailer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;with&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;welcome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;deliver_now&lt;/span&gt; &lt;span class="c1"&gt;# ← you get stuck waiting a few seconds here&lt;/span&gt;
    &lt;span class="n"&gt;render&lt;/span&gt; &lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is like the cashier &lt;strong&gt;taking an order, walking into the kitchen to cook it themselves, and not coming back to the register until it's done&lt;/strong&gt;. Everyone in line behind has to wait the whole time.&lt;/p&gt;

&lt;p&gt;For &lt;strong&gt;slow work&lt;/strong&gt; like sending emails, exporting CSVs, or calling external APIs, we want to say "we'll do that later" and get back to the customer right away. That's where jobs come in.&lt;/p&gt;




&lt;h2&gt;
  
  
  Job = order ticket
&lt;/h2&gt;

&lt;p&gt;A job is an &lt;strong&gt;order ticket&lt;/strong&gt; that says "please take care of this."&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;WelcomeMailJob&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="nc"&gt;ApplicationJob&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;perform&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;User&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nc"&gt;WelcomeMailer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;with&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;welcome&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;deliver_now&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The cashier (controller) just writes the ticket and pins it to the board.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;create&lt;/span&gt;
  &lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;User&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user_params&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="nc"&gt;WelcomeMailJob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;perform_later&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="c1"&gt;# ← just pins the ticket. Done in an instant&lt;/span&gt;
  &lt;span class="n"&gt;render&lt;/span&gt; &lt;span class="n"&gt;json&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;perform_later&lt;/code&gt; literally means "perform this later." The cashier can go right back to the next customer.&lt;/p&gt;

&lt;h3&gt;
  
  
  Write the "table number" on the ticket, not the "dish"
&lt;/h3&gt;

&lt;p&gt;Notice we pass &lt;code&gt;user.id&lt;/code&gt;, not &lt;code&gt;user&lt;/code&gt; itself, as the argument.&lt;/p&gt;

&lt;p&gt;Nobody tapes the actual dish to an order ticket. You write "Table 3, hamburger steak," and the cook checks the latest info when it's time to cook. Jobs work the same way: the basic rule is &lt;strong&gt;pass just the ID, and re-fetch from the DB when the job runs&lt;/strong&gt;. The data might have changed between being queued and actually running.&lt;/p&gt;




&lt;h2&gt;
  
  
  Queue = order ticket board
&lt;/h2&gt;

&lt;p&gt;A queue is &lt;strong&gt;a board that keeps order tickets lined up in the order they arrived&lt;/strong&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt; Cashier                Order ticket board (queue)         Cook (worker)
┌──────┐   pin    ┌──────────────────────────┐  take   ┌──────┐
│      │ ───────▶ │ [T3] [T2] [T1]           │ ──────▶ │ Cook │
└──────┘          └──────────────────────────┘         └──────┘
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;The cashier &lt;strong&gt;only pins&lt;/strong&gt;, the cook &lt;strong&gt;only takes and cooks&lt;/strong&gt;. Neither waits on the other&lt;/li&gt;
&lt;li&gt;The cook is always on standby in the kitchen and grabs a ticket as soon as it's pinned&lt;/li&gt;
&lt;li&gt;If orders flood in, the tickets &lt;strong&gt;just line up&lt;/strong&gt; on the board. The kitchen doesn't get overwhelmed&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  "Why not just hire a cook for every order?"
&lt;/h3&gt;

&lt;p&gt;You might think: skip the board and hire a new cook for each order to start cooking immediately. In Rails terms, that's "spin up a new process for every job."&lt;/p&gt;

&lt;p&gt;That doesn't work, for these reasons:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Hiring is expensive&lt;/strong&gt;: a Rails process takes several seconds to boot and hundreds of MB of memory. The training cost every time is way too high&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Too many of them&lt;/strong&gt;: if 1,000 orders come in per second, 1,000 people pile into the kitchen at once. Memory and DB connections (the size of the kitchen and the number of burners) hit their limits before the CPU does&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Orders vanish&lt;/strong&gt;: if a cook collapses mid-order, that order disappears without anyone knowing&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;No do-overs&lt;/strong&gt;: if something fails, nobody remakes it&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;With a board and resident cooks, you can &lt;strong&gt;keep the headcount fixed, never lose an order, and reliably get everything done&lt;/strong&gt;. A queue isn't "a mechanism for making people wait"; it's a mechanism for exactly that.&lt;/p&gt;




&lt;h2&gt;
  
  
  Adapter = type of board
&lt;/h2&gt;

&lt;p&gt;There are all kinds of order ticket boards: a whiteboard, paper slips, an order system connected to HQ...&lt;/p&gt;

&lt;p&gt;ActiveJob is built so that &lt;strong&gt;you write order tickets the same way no matter which board you use&lt;/strong&gt;. The "plug converter" that absorbs the differences between boards is the adapter.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="c1"&gt;# You write order tickets the same way for every board&lt;/span&gt;
&lt;span class="nc"&gt;WelcomeMailJob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;perform_later&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

&lt;span class="c1"&gt;# Which board to use is switched with one line of config&lt;/span&gt;
&lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;active_job&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;queue_adapter&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="ss"&gt;:async&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Let's look at the common boards.&lt;/p&gt;

&lt;h3&gt;
  
  
  &lt;code&gt;:async&lt;/code&gt; ─ the staff just keep it in their heads
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;┌──────────── The restaurant (one Rails process) ────────────┐
│  Cashier ──▶ notes in the staff's head ──▶ in-house cook    │
└─────────────────────────────────────────────────────────────┘
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is the Rails default. The queue and the cooks are &lt;strong&gt;all inside the Rails process&lt;/strong&gt;.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;It works without installing anything extra, so it's &lt;strong&gt;handy for learning and development&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;But the orders only exist &lt;strong&gt;in the staff's heads&lt;/strong&gt;. Close the restaurant (restart the process, deploy) and every order that hasn't been cooked yet is &lt;strong&gt;completely forgotten&lt;/strong&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  &lt;code&gt;:inline&lt;/code&gt; ─ the cashier cooks it on the spot
&lt;/h3&gt;

&lt;p&gt;No board; the cashier &lt;strong&gt;cooks it themselves right then and there&lt;/strong&gt;. Even if you write &lt;code&gt;perform_later&lt;/code&gt;, it doesn't run asynchronously.&lt;/p&gt;

&lt;p&gt;Handy during development when you want to quickly check "does this job actually work?"&lt;/p&gt;

&lt;h3&gt;
  
  
  &lt;code&gt;:test&lt;/code&gt; ─ the training board
&lt;/h3&gt;

&lt;p&gt;It doesn't actually cook anything; it &lt;strong&gt;only records "was the order ticket pinned correctly?"&lt;/strong&gt; You use it when testing with RSpec.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;expect&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;post&lt;/span&gt; &lt;span class="s1"&gt;'/users'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;params&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;to&lt;/span&gt; &lt;span class="nf"&gt;have_enqueued_job&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;WelcomeMailJob&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  &lt;code&gt;:solid_queue&lt;/code&gt; / &lt;code&gt;:sidekiq&lt;/code&gt; / &lt;code&gt;:sqs&lt;/code&gt; etc. ─ a board outside the restaurant
&lt;/h3&gt;

&lt;p&gt;For production. Order tickets are recorded in &lt;strong&gt;an order system outside the restaurant&lt;/strong&gt; (a DB, Redis, Amazon SQS, etc.).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;┌── Restaurant (Rails process) ──┐      ┌── Order system outside ──┐
│  Cashier                        │ ───▶ │  Order ticket board       │
└─────────────────────────────────┘      └───────────────────────────┘
   ↑ No matter how many times it          ↑ The orders stay here
     closes and reopens
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;Even if the restaurant closes (Rails restarts or deploys), &lt;strong&gt;the orders stay&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;You can put cooks in &lt;strong&gt;a different kitchen (a different server)&lt;/strong&gt; and add as many as you need&lt;/li&gt;
&lt;li&gt;Failed orders can be &lt;strong&gt;re-pinned&lt;/strong&gt; with "try again in 5 minutes"&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That said, how much survives if the board itself breaks depends on the board.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Redis&lt;/strong&gt; also keeps things in memory. If you haven't set up persistence (snapshots or an append-only log), a Redis restart wipes it out&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;DB&lt;/strong&gt; and &lt;strong&gt;SQS&lt;/strong&gt; store data on disk or across multiple locations, so they're less likely to lose things&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The real difference from &lt;code&gt;:async&lt;/code&gt; isn't "memory vs. disk"; it's &lt;strong&gt;whether the board closes along with the restaurant (Rails)&lt;/strong&gt;.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Adapter&lt;/th&gt;
&lt;th&gt;Where the board lives&lt;/th&gt;
&lt;th&gt;Lost on Rails restart?&lt;/th&gt;
&lt;th&gt;Lost when the board itself restarts?&lt;/th&gt;
&lt;th&gt;Main use&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;:async&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;In the staff's heads (Rails memory)&lt;/td&gt;
&lt;td&gt;Lost&lt;/td&gt;
&lt;td&gt;─&lt;/td&gt;
&lt;td&gt;Learning / development&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;:inline&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;None (cooked on the spot)&lt;/td&gt;
&lt;td&gt;─&lt;/td&gt;
&lt;td&gt;─&lt;/td&gt;
&lt;td&gt;Development / debugging&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;:test&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Training records&lt;/td&gt;
&lt;td&gt;─&lt;/td&gt;
&lt;td&gt;─&lt;/td&gt;
&lt;td&gt;Testing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;:sidekiq&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Redis (memory on another server)&lt;/td&gt;
&lt;td&gt;Not lost&lt;/td&gt;
&lt;td&gt;Depends on persistence settings&lt;/td&gt;
&lt;td&gt;Production&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;:solid_queue&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;DB (disk)&lt;/td&gt;
&lt;td&gt;Not lost&lt;/td&gt;
&lt;td&gt;Almost never lost&lt;/td&gt;
&lt;td&gt;Production&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;:sqs&lt;/code&gt; family&lt;/td&gt;
&lt;td&gt;Amazon SQS&lt;/td&gt;
&lt;td&gt;Not lost&lt;/td&gt;
&lt;td&gt;Stored across multiple locations, hard to lose&lt;/td&gt;
&lt;td&gt;Production&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;




&lt;h2&gt;
  
  
  Things to watch out for in production
&lt;/h2&gt;

&lt;p&gt;Once you use a board outside the restaurant, problems show up that you never saw with &lt;code&gt;:async&lt;/code&gt; or &lt;code&gt;:inline&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. The same order ticket can arrive twice
&lt;/h3&gt;

&lt;p&gt;With distributed queues like SQS, &lt;strong&gt;the same job can occasionally run twice&lt;/strong&gt;. Getting two hamburger steaks would be a problem, right?&lt;/p&gt;

&lt;p&gt;Build your jobs so that "running them any number of times gives the same result" (&lt;strong&gt;idempotency&lt;/strong&gt;). For example, "if the sent flag is already set, do nothing."&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Don't pin the ticket before the bill is settled
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="nc"&gt;ActiveRecord&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nc"&gt;Base&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;transaction&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;User&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user_params&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="nc"&gt;WelcomeMailJob&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;perform_later&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="c1"&gt;# ← dangerous&lt;/span&gt;
  &lt;span class="c1"&gt;# ...what if an exception happens after this and it rolls back?&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you call &lt;code&gt;perform_later&lt;/code&gt; inside a transaction, these things can happen:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The cook sees the ticket first and heads to the kitchen, but &lt;strong&gt;the order isn't confirmed yet&lt;/strong&gt; (it's before the commit, so &lt;code&gt;User.find&lt;/code&gt; can't find it)&lt;/li&gt;
&lt;li&gt;The order was &lt;strong&gt;canceled&lt;/strong&gt; (rolled back), but the cook already started cooking&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Pin the ticket &lt;strong&gt;after the bill is settled&lt;/strong&gt; (after the transaction commits). Using &lt;code&gt;after_commit&lt;/code&gt; is the standard approach.&lt;/p&gt;

&lt;p&gt;Also, Rails 7.2 and later have a mechanism (&lt;code&gt;enqueue_after_transaction_commit&lt;/code&gt;) that delays jobs enqueued during a transaction until after the commit.&lt;/p&gt;

</description>
      <category>rails</category>
      <category>ruby</category>
    </item>
    <item>
      <title>A Rough Guide to Entities, Value Objects, Services, and UseCases</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:39:22 +0000</pubDate>
      <link>https://dev.to/kaziusan/a-rough-guide-to-entities-value-objects-services-and-usecases-4bce</link>
      <guid>https://dev.to/kaziusan/a-rough-guide-to-entities-value-objects-services-and-usecases-4bce</guid>
      <description>&lt;p&gt;Well, this is less about Rails and more DDD (Domain-Driven Design) and Clean Architecture territory, but hey&lt;/p&gt;




&lt;h2&gt;
  
  
  At a glance
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Term&lt;/th&gt;
&lt;th&gt;In a nutshell&lt;/th&gt;
&lt;th&gt;Examples&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Entity&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Something you tell apart by ID&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;User, deal, order&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Value object&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Something you tell apart by its contents&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Amount of money, phone number, address, period&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Service object&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;A box for putting procedures in&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Calculating tax, uploading to S3&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;UseCase&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;One thing the user wants to do&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Registering a deal, confirming an order&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;




&lt;h2&gt;
  
  
  Entity ─ something you tell apart by ID
&lt;/h2&gt;

&lt;p&gt;A person is &lt;strong&gt;the same person&lt;/strong&gt; even if they change their last name or move. On the flip side, two people with the same name and the same age are still &lt;strong&gt;different people&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Like this, an entity is &lt;strong&gt;something you tell apart by its ID (the fact that it's &lt;em&gt;that&lt;/em&gt; one)&lt;/strong&gt;, not by its contents.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;User&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'Suzuki'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="c1"&gt;# Even if the name changes, it's still id: 1. The same user&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In Rails, most ActiveRecord models with an &lt;code&gt;id&lt;/code&gt; are entities.&lt;/p&gt;




&lt;h2&gt;
  
  
  Value object ─ something you tell apart by its contents
&lt;/h2&gt;

&lt;p&gt;If you swap the 1,000-yen bill in my wallet with yours, nobody cares. We don't care about the serial number; &lt;strong&gt;if the contents (the amount) are the same, it's the same thing&lt;/strong&gt;. That's a value object.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="nc"&gt;PhoneNumber&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;define&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="ss"&gt;:value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;initialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nb"&gt;raise&lt;/span&gt; &lt;span class="nc"&gt;ArgumentError&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'Invalid phone number'&lt;/span&gt; &lt;span class="k"&gt;unless&lt;/span&gt; &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;match?&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;\&lt;span class="no"&gt;A0&lt;/span&gt;\&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="mi"&gt;9&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;\&lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;

    &lt;span class="k"&gt;super&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;mobile?&lt;/span&gt;
    &lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;match?&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;\&lt;span class="no"&gt;A0&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;7&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;9&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;\&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="mi"&gt;8&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;\&lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;

&lt;span class="nc"&gt;PhoneNumber&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'09012345678'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="nc"&gt;PhoneNumber&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;value&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'09012345678'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="c1"&gt;# =&amp;gt; true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It has these three traits:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;No ID&lt;/strong&gt;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Its contents don't change&lt;/strong&gt; (if you want to change them, you create a new one)&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It can hold rules&lt;/strong&gt; ("10–11 digits starting with 0," "check whether it's a mobile number," etc.)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you keep phone numbers as plain Strings, the "check whether it's a mobile number" logic ends up copy-pasted into User, into Company, and so on. Make it a value object and all the phone number rules live in one place.&lt;/p&gt;




&lt;h2&gt;
  
  
  Service object ─ a box for putting procedures in
&lt;/h2&gt;

&lt;p&gt;It's a class for holding &lt;strong&gt;procedures that would bloat a model if you put them in it&lt;/strong&gt;, like "calculate tax" or "upload a file to S3."&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;TaxCalculator&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;initialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;amount&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="vi"&gt;@amount&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;amount&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;

  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;call&lt;/span&gt;
    &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="vi"&gt;@amount&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mf"&gt;0.1&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;floor&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Common conventions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;One job per class&lt;/li&gt;
&lt;li&gt;Only one public method, like &lt;code&gt;call&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Give it a name that tells you "what it does" (avoid vague names like &lt;code&gt;UserService&lt;/code&gt;)&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  Service = business logic?
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Not exactly&lt;/strong&gt;. Business rules also go into entities and value objects, and services also hold technical stuff like "upload to S3." It's more accurate to think of a service as "&lt;strong&gt;one of the places business logic can live&lt;/strong&gt;."&lt;/p&gt;




&lt;h2&gt;
  
  
  UseCase ─ one thing the user wants to do
&lt;/h2&gt;

&lt;p&gt;It's a class representing &lt;strong&gt;one thing the user wants to do in the app&lt;/strong&gt;, like "register a deal" or "confirm an order." Picture the app's feature list turned directly into classes.&lt;/p&gt;

&lt;p&gt;A UseCase is &lt;strong&gt;the conductor&lt;/strong&gt;. It doesn't do the fine-grained work itself; it calls entities and services to put the steps together.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight ruby"&gt;&lt;code&gt;&lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;ConfirmOrderUseCase&lt;/span&gt;
  &lt;span class="k"&gt;def&lt;/span&gt; &lt;span class="nf"&gt;call&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;order_id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order_id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="nb"&gt;raise&lt;/span&gt; &lt;span class="s1"&gt;'Not authorized'&lt;/span&gt; &lt;span class="k"&gt;unless&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;user_id&lt;/span&gt; &lt;span class="o"&gt;==&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;     &lt;span class="c1"&gt;# permission check&lt;/span&gt;

    &lt;span class="nc"&gt;ActiveRecord&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nc"&gt;Base&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;transaction&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
      &lt;span class="n"&gt;tax&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;TaxCalculator&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;subtotal&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;call&lt;/span&gt;                &lt;span class="c1"&gt;# use a service&lt;/span&gt;
      &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;update!&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;tax&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;tax&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="ss"&gt;:confirmed&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;                 &lt;span class="c1"&gt;# update the entity&lt;/span&gt;
    &lt;span class="k"&gt;end&lt;/span&gt;
  &lt;span class="k"&gt;end&lt;/span&gt;
&lt;span class="k"&gt;end&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Depending on the team, a UseCase might go by another name like &lt;strong&gt;Operation&lt;/strong&gt;, &lt;strong&gt;Interactor&lt;/strong&gt;, or &lt;strong&gt;Command&lt;/strong&gt;. Different names, same role: "the procedure for one user action."&lt;/p&gt;




&lt;h2&gt;
  
  
  How the four fit together
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;UseCase "Confirm an order" (conductor)
   │
   ├─ Reads/writes entities         … Order
   │      └─ which hold value objects … amount, phone number
   │
   └─ Calls services                … tax calculation, sending email, S3
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;The &lt;strong&gt;UseCase&lt;/strong&gt; decides the game plan&lt;/li&gt;
&lt;li&gt;Within it, it manipulates &lt;strong&gt;entities&lt;/strong&gt; and hands work off to &lt;strong&gt;services&lt;/strong&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Value objects&lt;/strong&gt; are used as "values" inside entities and services&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Calls go &lt;strong&gt;one way, top to bottom&lt;/strong&gt;. A service never calls a UseCase.&lt;/p&gt;

</description>
      <category>rails</category>
      <category>architecture</category>
    </item>
    <item>
      <title>NestJS Core Architecture and How We Used It in a Real Project</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:31:10 +0000</pubDate>
      <link>https://dev.to/kaziusan/nestjs-core-architecture-and-how-we-used-it-in-a-real-project-1fll</link>
      <guid>https://dev.to/kaziusan/nestjs-core-architecture-and-how-we-used-it-in-a-real-project-1fll</guid>
      <description>&lt;p&gt;※ The code examples in this article are based on a real product, but project names, service names, variable names, and anything else that could identify a specific product have been changed or generalized.&lt;/p&gt;

&lt;p&gt;(I didn't write all of this from scratch. I took AI-generated content and fixed it up, so I could use it as a kind of dictionary for the project.)&lt;/p&gt;

&lt;p&gt;NestJS is a server-side framework built with TypeScript, known for its module-oriented architecture inspired by Angular. In this article, I'll explain the core concepts of NestJS and show how we used them in a real SaaS product (GraphQL API / multi-tenant setup).&lt;/p&gt;

&lt;p&gt;(*Update) ↑ I made that sound impressive, but I didn't actually work on that project much, so honestly most of this article isn't in my head lol&lt;/p&gt;




&lt;h2&gt;
  
  
  Table of contents
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Module&lt;/li&gt;
&lt;li&gt;Controller / Resolver&lt;/li&gt;
&lt;li&gt;Service / UseCase&lt;/li&gt;
&lt;li&gt;DI (Dependency Injection)&lt;/li&gt;
&lt;li&gt;Guard (Authentication and Authorization)&lt;/li&gt;
&lt;li&gt;Layered Entity Definitions&lt;/li&gt;
&lt;li&gt;Prisma Integration (Repository + Mapper)&lt;/li&gt;
&lt;li&gt;How the Auth Context Flows&lt;/li&gt;
&lt;li&gt;Summary: Standard NestJS vs. a Real Project&lt;/li&gt;
&lt;/ol&gt;




&lt;h2&gt;
  
  
  1. Module
&lt;/h2&gt;

&lt;h3&gt;
  
  
  NestJS basics
&lt;/h3&gt;

&lt;p&gt;A NestJS application is organized in units called &lt;strong&gt;Modules&lt;/strong&gt;. With the &lt;code&gt;@Module()&lt;/code&gt; decorator, you define &lt;code&gt;providers&lt;/code&gt; (services it provides), &lt;code&gt;imports&lt;/code&gt; (modules it depends on), and &lt;code&gt;exports&lt;/code&gt; (services it exposes to others), which together configure the DI container.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Module&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CatService&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;imports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;DatabaseModule&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;exports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CatService&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CatModule&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  In the real project
&lt;/h3&gt;

&lt;p&gt;In this project, modules are split into three layers following a layered architecture.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;app.module.ts
  ├─ ResolverModules (interface/di/)        ← presentation layer
  ├─ UseCaseModules (app/di/)               ← application layer
  └─ RepositoryModules (infra/prisma/di/)   ← infrastructure layer
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The directory structure looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;packages/api/src/
├── app/                      # Application layer
│   ├── di/                   # UseCase module definitions
│   └── useCases/             # UseCase implementations
├── domain/                   # Domain layer
│   ├── entities/             # Domain entities and type definitions
│   ├── restrictFilters/      # Permission filters
│   └── common/               # Shared types and utilities
├── interface/                # Interface layer
│   ├── di/                   # Resolver module definitions
│   ├── resolvers/            # GraphQL resolvers
│   ├── schema/               # Request/response types
│   └── auth/                 # Auth guards
├── infra/                    # Infrastructure layer
│   ├── prisma/               # Repositories and mappers
│   └── ...                   # External service integrations
└── entities/                 # GraphQL ObjectType definitions
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A ResolverModule resolves its dependencies by &lt;code&gt;imports&lt;/code&gt;-ing UseCaseModules.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Module&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CommentResolver&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;imports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="nc"&gt;CommentUseCaseModule&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nc"&gt;UserUseCaseModule&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CommentResolverModule&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A UseCaseModule &lt;code&gt;imports&lt;/code&gt; RepositoryModules and other ServiceModules.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Module&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CommentUseCase&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;exports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CommentUseCase&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;imports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="nc"&gt;PrismaCommentRepositoryModule&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nc"&gt;PrismaRoomRepositoryModule&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nc"&gt;NotificationServiceModule&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CommentUseCaseModule&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Key point&lt;/strong&gt;: We use NestJS's module system to enforce a clean-architecture-style dependency direction (interface → app → domain ← infra).&lt;/p&gt;




&lt;h2&gt;
  
  
  2. Controller / Resolver
&lt;/h2&gt;

&lt;h3&gt;
  
  
  NestJS basics
&lt;/h3&gt;

&lt;p&gt;For a REST API, you use decorators like &lt;code&gt;@Get()&lt;/code&gt; / &lt;code&gt;@Post()&lt;/code&gt; on a &lt;code&gt;@Controller()&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Controller&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'cats'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CatController&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nd"&gt;@Get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="nf"&gt;findAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s1"&gt;'All cats'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nd"&gt;@Post&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nd"&gt;@Body&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;dto&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CreateCatDto&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For GraphQL, you use &lt;code&gt;@Query()&lt;/code&gt; / &lt;code&gt;@Mutation()&lt;/code&gt; / &lt;code&gt;@ResolveField()&lt;/code&gt; on a &lt;code&gt;@Resolver()&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  In the real project
&lt;/h3&gt;

&lt;p&gt;This project uses GraphQL with a &lt;strong&gt;code-first&lt;/strong&gt; approach, generating the schema automatically.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// app.module.ts&lt;/span&gt;
&lt;span class="nc"&gt;GraphQLModule&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;forRoot&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;ApolloDriverConfig&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;driver&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ApolloDriver&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;autoSchemaFile&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;cwd&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'src/schema.gql'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// generated from TypeScript&lt;/span&gt;
  &lt;span class="n"&gt;fieldResolverEnhancers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'guards'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A resolver example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Resolver&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;GqlComment&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CommentResolver&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;commentUseCase&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CommentUseCase&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// Query: fetch data&lt;/span&gt;
  &lt;span class="nd"&gt;@UseGuards&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;AuthGuard&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="nd"&gt;@Query&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;GqlComment&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;commentList&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nd"&gt;@Args&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'input'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;GetCommentListInput&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nd"&gt;@Context&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;OperationContext&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;commentUseCase&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getCommentList&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// Mutation: change data&lt;/span&gt;
  &lt;span class="nd"&gt;@UseGuards&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;AuthGuard&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="nd"&gt;@Mutation&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;GqlComment&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;createComment&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="nd"&gt;@Args&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'input'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CreateCommentInput&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nd"&gt;@Context&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;OperationContext&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;commentUseCase&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;createComment&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="c1"&gt;// ResolveField: resolve a nested field&lt;/span&gt;
  &lt;span class="nd"&gt;@ResolveField&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'author'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;GqlUser&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;getAuthor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nd"&gt;@Parent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;comment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Comment&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;userUseCase&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findOne&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;comment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;userId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h4&gt;
  
  
  Main decorators
&lt;/h4&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Decorator&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@Resolver(() =&amp;gt; Type)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Declares the class as a resolver&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@Query(() =&amp;gt; Type)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Defines a GraphQL query&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@Mutation(() =&amp;gt; Type)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Defines a GraphQL mutation&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@ResolveField('name', () =&amp;gt; Type)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Resolves a nested field&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@Args('input')&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Binds input arguments&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@Parent()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Accesses the parent object&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;@Context()&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Gets the GraphQL context (auth info, etc.)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h4&gt;
  
  
  InputType (request type)
&lt;/h4&gt;

&lt;p&gt;GraphQL input types are also defined with decorators.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@InputType&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CreateCommentInput&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nd"&gt;@Field&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;GraphQLJSON&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;JsonObject&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="nd"&gt;@Field&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;roomId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="nd"&gt;@Field&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;Int&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;nullable&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;imageIds&lt;/span&gt;&lt;span class="o"&gt;?:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This automatically generates the following GraphQL schema:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight graphql"&gt;&lt;code&gt;&lt;span class="n"&gt;input&lt;/span&gt; &lt;span class="nc"&gt;CreateCommentInput&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="no"&gt;JSON&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;
  &lt;span class="n"&gt;roomId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="no"&gt;ID&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;
  &lt;span class="n"&gt;imageIds&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;Int&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  3. Service / UseCase
&lt;/h2&gt;

&lt;h3&gt;
  
  
  NestJS basics
&lt;/h3&gt;

&lt;p&gt;You use a class with the &lt;code&gt;@Injectable()&lt;/code&gt; decorator as a service, and gather business logic there.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Injectable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CatService&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;catRepository&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CatRepository&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nf"&gt;findAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;catRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  In the real project
&lt;/h3&gt;

&lt;p&gt;In this project, we name these &lt;strong&gt;"UseCase"&lt;/strong&gt; instead of "Service", and split classes by use case.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Injectable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CommentUseCase&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;commentRepository&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;PrismaCommentRepository&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;roomRepository&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;PrismaRoomRepository&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;notificationService&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;NotificationService&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;createComment&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;OperationContext&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// 1. Domain validation&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;room&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;CoreAssert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;isNotEmpty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;roomRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findOneById&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;roomId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="c1"&gt;// 2. Create the domain entity&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;comment&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createCommentSeed&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;executor&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="c1"&gt;// 3. Save to the DB&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;created&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;commentRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;comment&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="c1"&gt;// 4. Notifications and external integrations&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;notificationService&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;send&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;created&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Key point&lt;/strong&gt;: Inside a UseCase, the flow is domain validation → DB save → side effects (notifications, external integrations). Repositories and external services are all injected through the constructor, which makes it very testable.&lt;/p&gt;




&lt;h2&gt;
  
  
  4. DI (Dependency Injection)
&lt;/h2&gt;

&lt;h3&gt;
  
  
  NestJS basics
&lt;/h3&gt;

&lt;p&gt;NestJS's DI automatically resolves providers from &lt;strong&gt;TypeScript type information&lt;/strong&gt;. You register an &lt;code&gt;@Injectable()&lt;/code&gt; class in a module's &lt;code&gt;providers&lt;/code&gt;, and it's injected automatically based on the constructor's types.&lt;/p&gt;

&lt;h3&gt;
  
  
  In the real project
&lt;/h3&gt;

&lt;p&gt;Dependencies that cross layers are controlled with &lt;code&gt;imports&lt;/code&gt; / &lt;code&gt;exports&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nc"&gt;Resolver&lt;/span&gt; → &lt;span class="nf"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;useCase&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CommentUseCase&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;     &lt;span class="c1"&gt;// resolved by type&lt;/span&gt;
&lt;span class="nc"&gt;UseCase&lt;/span&gt;  → &lt;span class="nf"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;repo&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;PrismaCommentRepository&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="c1"&gt;// resolved by type&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On the module side:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// UseCaseModule: expose CommentUseCase to the outside&lt;/span&gt;
&lt;span class="nd"&gt;@Module&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CommentUseCase&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;exports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CommentUseCase&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;          &lt;span class="c1"&gt;// usable from other modules&lt;/span&gt;
  &lt;span class="n"&gt;imports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;PrismaCommentRepositoryModule&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CommentUseCaseModule&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;// ResolverModule: import the UseCaseModule to use it&lt;/span&gt;
&lt;span class="nd"&gt;@Module&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;providers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CommentResolver&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;imports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CommentUseCaseModule&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;    &lt;span class="c1"&gt;// CommentUseCase becomes available&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;CommentResolverModule&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When you hit a circular dependency, you work around it with &lt;code&gt;forwardRef()&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Module&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;imports&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nf"&gt;forwardRef&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;RelatedModule&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;SomeModule&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  5. Guard (Authentication and Authorization)
&lt;/h2&gt;

&lt;h3&gt;
  
  
  NestJS basics
&lt;/h3&gt;

&lt;p&gt;You create a guard class that implements the &lt;code&gt;CanActivate&lt;/code&gt; interface and apply it with the &lt;code&gt;@UseGuards()&lt;/code&gt; decorator.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Injectable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;AuthGuard&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;CanActivate&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;canActivate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ExecutionContext&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;switchToHttp&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getRequest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nf"&gt;validateToken&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;authorization&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  In the real project
&lt;/h3&gt;

&lt;p&gt;Because this project is a multi-user SaaS, we use a pattern that routes to different auth guards depending on the user type (admin / guest).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Injectable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;MultiUserAuthGuard&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;CanActivate&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;adminAuthGuard&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;AdminAuthGuard&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;guestAuthGuard&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;GuestAuthGuard&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;canActivate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ExecutionContext&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;boolean&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;ctx&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;GqlExecutionContext&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getContext&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;userType&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s1"&gt;'x-user-type'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;userType&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'Admin'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="c1"&gt;// JWT verification (external auth service)&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;adminAuthGuard&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;canActivate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;userType&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="s1"&gt;'Guest'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="c1"&gt;// Session token verification&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;guestAuthGuard&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;canActivate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;UnauthorizedException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;We also implement fine-grained permission control at the &lt;code&gt;@ResolveField&lt;/code&gt; level.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@ResolveField&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'author'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;GqlUser&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nd"&gt;@UseGuards&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;UserTypesGuard&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="nd"&gt;@RequiredUserTypes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'ADMIN'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;  &lt;span class="c1"&gt;// metadata set via a custom decorator&lt;/span&gt;
&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;getAuthor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nd"&gt;@Parent&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;comment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Comment&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;userUseCase&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findOne&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;comment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;userId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;UserTypesGuard&lt;/code&gt; reads that metadata with &lt;code&gt;Reflector&lt;/code&gt; and checks permissions.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Injectable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;UserTypesGuard&lt;/span&gt; &lt;span class="k"&gt;implements&lt;/span&gt; &lt;span class="nc"&gt;CanActivate&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nf"&gt;constructor&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="n"&gt;reflector&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Reflector&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="nf"&gt;canActivate&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ExecutionContext&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;boolean&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;requiredTypes&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;reflector&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;get&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
      &lt;span class="s1"&gt;'requiredUserTypes'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getHandler&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;requiredTypes&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;gqlContext&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;GqlExecutionContext&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;gqlContext&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getContext&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;requiredTypes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;includes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;executor&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;userType&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  6. Layered Entity Definitions
&lt;/h2&gt;

&lt;h3&gt;
  
  
  NestJS basics
&lt;/h3&gt;

&lt;p&gt;In a typical NestJS application, a single entity class often serves as both the DB definition and the API definition.&lt;/p&gt;

&lt;h3&gt;
  
  
  In the real project
&lt;/h3&gt;

&lt;p&gt;This project uses &lt;strong&gt;three layers of entity definitions&lt;/strong&gt;.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Layer&lt;/th&gt;
&lt;th&gt;Example file&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;GraphQL Entity&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;entities/Comment.entity.ts&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Defines the API output type with &lt;code&gt;@ObjectType()&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Domain Entity&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;domain/entities/Comment/index.ts&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Type-safe business model using brand types&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Prisma Model&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;prisma/schema.prisma&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;DB schema definition&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h4&gt;
  
  
  GraphQL Entity (API layer)
&lt;/h4&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@ObjectType&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Comment&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nd"&gt;@Field&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;Int&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="nd"&gt;@Field&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nc"&gt;GraphQLJSON&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;JsonObject&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="nd"&gt;@Field&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;createdAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="nd"&gt;@Field&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nc"&gt;CommentImage&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="n"&gt;commentImages&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CommentImage&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;  &lt;span class="c1"&gt;// nested field&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h4&gt;
  
  
  Domain Entity (domain layer)
&lt;/h4&gt;

&lt;p&gt;Brand types let you tell different kinds of IDs apart, even though they're all &lt;code&gt;number&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Brand type definition&lt;/span&gt;
&lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;Brand&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="no"&gt;T&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="no"&gt;U&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="no"&gt;T&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;__brand&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="no"&gt;U&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Distinguish IDs at the type level&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;CommentId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Brand&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'CommentId'&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;UserId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;Brand&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;number&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'UserId'&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Type error: CommentId and UserId are not compatible&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;commentId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CommentId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nc"&gt;CommentId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;UserId&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;commentId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// compile error!&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The domain entity definition:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;Comment&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CommentId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;JsonObject&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;roomId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;RoomId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;UserId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;TenantId&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;createdAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="n"&gt;updatedAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Factory function&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;createCommentSeed&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;payload&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CommentSeed&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CommentSeed&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;payload&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h4&gt;
  
  
  Prisma Model (DB layer)
&lt;/h4&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;model Comment {
  id        Int       @id @default(autoincrement())
  content   Json?
  roomId    String
  Room      Room      @relation(fields: [roomId], references: [id], onDelete: Cascade)
  userId    Int
  createdAt DateTime  @default(now())
  updatedAt DateTime  @default(now()) @updatedAt
}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Key point&lt;/strong&gt;: Splitting into three layers means API spec changes don't affect domain logic, and DB schema changes don't leak into the API layer.&lt;/p&gt;




&lt;h2&gt;
  
  
  7. Prisma Integration (Repository + Mapper)
&lt;/h2&gt;

&lt;h3&gt;
  
  
  NestJS basics
&lt;/h3&gt;

&lt;p&gt;In NestJS, it's common to use TypeORM or Prisma directly from services.&lt;/p&gt;

&lt;h3&gt;
  
  
  In the real project
&lt;/h3&gt;

&lt;p&gt;This project uses a Repository + Mapper pattern to convert Prisma types into domain types.&lt;/p&gt;

&lt;h4&gt;
  
  
  Repository
&lt;/h4&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="nd"&gt;@Injectable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;PrismaCommentRepository&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;CommentSeed&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Comment&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;prismaComment&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;comment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;contentJson&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;roomId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;roomId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;include&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Room&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="c1"&gt;// Convert Prisma type → domain type&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nc"&gt;PrismaCommentMapper&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toDomainComment&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;

  &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;findList&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nc"&gt;Comment&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;results&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;comment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findMany&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;roomId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;roomId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nc"&gt;Room&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tenantId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// tenant isolation&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;orderBy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;createdAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'asc'&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nc"&gt;PrismaCommentMapper&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;toDomainComment&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h4&gt;
  
  
  Mapper
&lt;/h4&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;PrismaCommentMapper&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="nf"&gt;toDomainComment&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Comment&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nc"&gt;CommentId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;contentJson&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nc"&gt;Prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;JsonObject&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;roomId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;roomId&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nc"&gt;RoomId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;userId&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nc"&gt;UserId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;Room&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tenantId&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nc"&gt;TenantId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;createdAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;createdAt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;updatedAt&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;prismaComment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;updatedAt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h4&gt;
  
  
  Transactions
&lt;/h4&gt;

&lt;p&gt;Operations that span multiple tables use &lt;code&gt;prisma.$transaction()&lt;/code&gt; to guarantee atomicity.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nv"&gt;$transaction&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;room&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;roomRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;roomData&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="kc"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;memberRepository&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;memberData&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;room&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Key point&lt;/strong&gt;: Repository methods take an optional &lt;code&gt;db&lt;/code&gt; argument, so they're designed to work both inside a transaction and standalone.&lt;/p&gt;




&lt;h2&gt;
  
  
  8. How the Auth Context Flows
&lt;/h2&gt;

&lt;p&gt;This is how auth information propagates in a multi-tenant SaaS.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;1. GraphQL request
   ├─ Header: Authorization: "Bearer &amp;lt;JWT&amp;gt;"
   └─ Header: x-user-type: "Admin" or "Guest"

2. Guard (authentication)
   ├─ Admin → verify JWT → build OperationContext
   └─ Guest → verify session → build OperationContext
   └─ set request.user = OperationContext

3. Resolver
   └─ get it via @Context() context: OperationContext

4. UseCase / Repository
   └─ use the context for permission control and tenant isolation
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;OperationContext&lt;/code&gt; is defined type-safely with a Zod schema.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;operationContextSchema&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;tenantIdSchema&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;executor&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;union&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;userType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;literal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'ADMIN'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;userIdSchema&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;role&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;roleSchema&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;userType&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;literal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'GUEST'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;userIdSchema&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt; &lt;span class="nc"&gt;OperationContext&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;infer&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="k"&gt;typeof&lt;/span&gt; &lt;span class="n"&gt;operationContextSchema&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It's injected into resolvers with the custom &lt;code&gt;@Context()&lt;/code&gt; decorator.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nc"&gt;Context&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;createParamDecorator&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;unknown&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;ExecutionContext&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;ctx&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nc"&gt;GqlExecutionContext&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;ctx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;getContext&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;req&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="nc"&gt;OperationContext&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Permission filters handle tenant isolation in DB operations.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;commentRestrictFilter&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;OperationContext&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;CommentWhereInput&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Room&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;tenantId&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tenantId&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// Usage&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;comments&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;prisma&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;comment&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findMany&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="n"&gt;where&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="no"&gt;AND&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;commentRestrictFilter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  9. Summary: Standard NestJS vs. a Real Project
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Aspect&lt;/th&gt;
&lt;th&gt;Standard NestJS&lt;/th&gt;
&lt;th&gt;Real project&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;API style&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;REST (&lt;code&gt;@Controller&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;GraphQL code-first (&lt;code&gt;@Resolver&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Business logic&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Service&lt;/td&gt;
&lt;td&gt;UseCase (split by use case)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Data access&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;ORM used directly&lt;/td&gt;
&lt;td&gt;Repository + Mapper pattern&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Auth&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Single guard&lt;/td&gt;
&lt;td&gt;Guard that routes by user type&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Type safety&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Standard TypeScript&lt;/td&gt;
&lt;td&gt;Brand types + Zod validation&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Tenant isolation&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;None&lt;/td&gt;
&lt;td&gt;OperationContext + RestrictFilter&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Entity&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Single definition&lt;/td&gt;
&lt;td&gt;3 layers (GraphQL / Domain / Prisma)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Module structure&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;By feature&lt;/td&gt;
&lt;td&gt;By layer (Resolver / UseCase / Repository)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;




&lt;h2&gt;
  
  
  Wrapping up
&lt;/h2&gt;

&lt;p&gt;NestJS is powerful enough out of the box, but it's also flexible enough to customize the architecture to fit a project's size and requirements.&lt;/p&gt;

&lt;p&gt;In this project, we built on NestJS's DI system and added a few things:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Layered architecture&lt;/strong&gt;: separate layers by module and control the dependency direction&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Code-first GraphQL&lt;/strong&gt;: generate the schema automatically from TypeScript decorators&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Brand types&lt;/strong&gt;: catch mixed-up IDs at compile time&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;RestrictFilter&lt;/strong&gt;: turn multi-tenant data isolation into a reusable pattern&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Once you understand the core NestJS concepts (Module / DI / Guard / Decorator), extending it to fit your project's needs is easy. I hope this helps.&lt;/p&gt;

</description>
      <category>architecture</category>
      <category>backend</category>
      <category>node</category>
      <category>typescript</category>
    </item>
    <item>
      <title>How One Stretched Image Led Me to Migrate AWS Lambda Code and Build CI/CD</title>
      <dc:creator>Kaziu</dc:creator>
      <pubDate>Mon, 16 Nov 2026 06:30:43 +0000</pubDate>
      <link>https://dev.to/kaziusan/how-one-stretched-image-led-me-to-migrate-aws-lambda-code-and-build-cicd-16g6</link>
      <guid>https://dev.to/kaziusan/how-one-stretched-image-led-me-to-migrate-aws-lambda-code-and-build-cicd-16g6</guid>
      <description>&lt;h2&gt;
  
  
  How it started
&lt;/h2&gt;

&lt;p&gt;One day, I noticed that a thumbnail image on a screen I was working on looked weirdly stretched.&lt;/p&gt;

&lt;p&gt;"Oh, I know this one. Just switch CSS &lt;code&gt;object-fit&lt;/code&gt; from &lt;code&gt;cover&lt;/code&gt; to &lt;code&gt;contain&lt;/code&gt; and done."&lt;/p&gt;

&lt;p&gt;Feeling pretty confident, I fixed the code. But the image was still stretched. When I opened the image URL directly from the browser's dev tools, the image coming back from Amazon S3 was &lt;em&gt;already&lt;/em&gt; stretched.&lt;/p&gt;

&lt;p&gt;"Are you kidding me?"&lt;/p&gt;

&lt;p&gt;But I had just joined the project, and I don't really know infrastructure. I had no idea where the image-generation code lived, so I asked a coworker.&lt;/p&gt;

&lt;p&gt;"Sorry to bother you — this thumbnail seems to be resized somewhere on the AWS side. Do you know where that happens?"&lt;/p&gt;

&lt;p&gt;My coworker said:&lt;/p&gt;

&lt;p&gt;"Oh, that's done by a Lambda function in a separate infrastructure repository. But editing that repository directly won't help. We need to move the code into the current application repository and set up CI/CD again."&lt;/p&gt;

&lt;p&gt;In my head it was like, "Ah, Lambda, I've heard of that… it's an AWS thing," but I decided to just give it a try.&lt;/p&gt;

&lt;h2&gt;
  
  
  STEP 1: What is Lambda anyway?
&lt;/h2&gt;

&lt;p&gt;It's "a small program that runs automatically when a specific event happens." It's one of the &lt;strong&gt;serverless&lt;/strong&gt; services, so you don't have to manage servers yourself. For example, it can run on events like these:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;When a file is uploaded to Amazon S3&lt;/li&gt;
&lt;li&gt;When a request comes in to API Gateway&lt;/li&gt;
&lt;li&gt;At a specific time (like cron)&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In this case, the setup was: "When an original image is uploaded to an S3 bucket, a Lambda function starts, generates a thumbnail, and saves it to another S3 bucket." So fixing the Lambda function's code looked like it would fix the stretched image too.&lt;/p&gt;

&lt;h2&gt;
  
  
  STEP 2: Migrating the Lambda function and building CI/CD
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Bring the Lambda function's source code from the old infrastructure repository into the current application repository.&lt;/li&gt;
&lt;li&gt;Fix that code so images don't get stretched. (This time I fixed the resize logic, changing the &lt;code&gt;resize&lt;/code&gt; method to the &lt;code&gt;thumbnail&lt;/code&gt; method.)&lt;/li&gt;
&lt;li&gt;Build a mechanism (CI/CD) with GitHub Actions that automatically deploys to the Lambda function on AWS when the code is updated.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;▼ Automatically deploying to Lambda with GitHub Actions&lt;br&gt;
Using a GitHub Actions workflow, set it up so that code is automatically deployed to AWS Lambda when it's pushed to a specific branch (e.g. main). The config goes in &lt;code&gt;.github/workflows&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# sample code
&lt;/span&gt;&lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Deploy to AWS Lambda&lt;/span&gt;

&lt;span class="na"&gt;on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;workflow_dispatch&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;inputs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="na"&gt;description&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s1"&gt;'Choose the environment to deploy to'&lt;/span&gt;
        &lt;span class="na"&gt;required&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
        &lt;span class="na"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;choice&lt;/span&gt;
        &lt;span class="na"&gt;options&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;release-candidate&lt;/span&gt;
          &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;staging&lt;/span&gt;
          &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="s"&gt;production&lt;/span&gt;

&lt;span class="na"&gt;jobs&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;deploy&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;runs-on&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ubuntu-latest&lt;/span&gt;
    &lt;span class="na"&gt;environment&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ github.event.inputs.environment }}&lt;/span&gt;
    &lt;span class="na"&gt;steps&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Checkout code&lt;/span&gt;
        &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;actions/checkout@v3&lt;/span&gt;

      &lt;span class="c1"&gt;# ... (set up Node.js or Python, install dependencies, etc.) ...
&lt;/span&gt;
      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Configure AWS Credentials&lt;/span&gt;
        &lt;span class="na"&gt;uses&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;aws-actions/configure-aws-credentials@v2&lt;/span&gt;
        &lt;span class="na"&gt;with&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
          &lt;span class="na"&gt;aws-access-key-id&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ secrets.AWS_ACCESS_KEY_ID }}&lt;/span&gt;
          &lt;span class="na"&gt;aws-secret-access-key&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;${{ secrets.AWS_SECRET_ACCESS_KEY }}&lt;/span&gt;
          &lt;span class="na"&gt;aws-region&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;ap-northeast-1&lt;/span&gt;

      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Build and Zip&lt;/span&gt;
        &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;|&lt;/span&gt;
          &lt;span class="c1"&gt;# build and packaging steps
&lt;/span&gt;          &lt;span class="s"&gt;zip -r function.zip .&lt;/span&gt;

      &lt;span class="p"&gt;-&lt;/span&gt; &lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Deploy to Lambda&lt;/span&gt;
        &lt;span class="na"&gt;run&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;|&lt;/span&gt;
          &lt;span class="s"&gt;aws lambda update-function-code \&lt;/span&gt;
            &lt;span class="s"&gt;--function-name ${{ secrets.YOUR_LAMBDA_FUNCTION_NAME }} \&lt;/span&gt;
            &lt;span class="s"&gt;--zip-file fileb://function.zip&lt;/span&gt;

&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;There are two key points in this workflow.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Using secrets per environment
&lt;/h3&gt;

&lt;p&gt;The GitHub repository had release-candidate, staging, and production environments under Settings &amp;gt; Environments. So in each environment's secrets, I registered the matching Lambda function name (e.g. rc-YourLambdaFunctionName) under the key &lt;code&gt;YOUR_LAMBDA_FUNCTION_NAME&lt;/code&gt;.&lt;br&gt;
When the workflow runs, the right function name is loaded automatically for the selected environment, which reduces the risk of deploying to the wrong place.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Safe deploys with a manual trigger
&lt;/h3&gt;

&lt;p&gt;Using &lt;code&gt;on: workflow_dispatch&lt;/code&gt; instead of &lt;code&gt;on: push&lt;/code&gt; prevents unintended automatic deploys. Developers just press the "Run workflow" button in the GitHub Actions tab and pick the environment, and the release goes out safely and reliably.&lt;/p&gt;

&lt;h3&gt;
  
  
  🔥 &lt;strong&gt;Gotcha: the "Run workflow" button doesn't show up in GitHub Actions!&lt;/strong&gt;
&lt;/h3&gt;

&lt;p&gt;This happened when I created the workflow and tried to test running it manually. Looking at the Actions tab of the GitHub repository, the manual "Run workflow" button just wasn't there.&lt;/p&gt;

&lt;p&gt;The reason was simple: the manual-run UI only appears once the workflow file containing &lt;code&gt;workflow_dispatch&lt;/code&gt; is merged into the repository's default branch (&lt;code&gt;main&lt;/code&gt; or &lt;code&gt;master&lt;/code&gt;).&lt;br&gt;
No matter how much you experiment on a development branch, the button won't appear. Not knowing this, I spent a good while fighting with GitHub.&lt;/p&gt;

&lt;h2&gt;
  
  
  Summary
&lt;/h2&gt;

&lt;p&gt;It was just one stretched image, but it pulled me into the world of AWS Lambda and CI/CD.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A display bug isn't always caused by the frontend or backend.&lt;/li&gt;
&lt;li&gt;AWS Lambda is a handy, event-driven automation program.&lt;/li&gt;
&lt;li&gt;Manual workflow runs (&lt;code&gt;workflow_dispatch&lt;/code&gt;) only become available from the default branch.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;And so the bug got fixed, and I felt great about it~&lt;/p&gt;

</description>
      <category>aws</category>
      <category>cicd</category>
    </item>
  </channel>
</rss>
