As the industry matures with these tools, it’s getting better - but it’s worth addressing directly because the habit reveals something deeper than just sloppy attribution.

LLMs Are Tools, Not Sources

When you say “GPT said X,” you’re doing two things at once, and both are wrong.

First, you’re treating an LLM as a source of authority. It’s not. An LLM is a tool that generates plausible text based on statistical patterns. It has no expertise, no reputation to protect, and no accountability. It can produce correct, well-reasoned output - and it can produce confident-sounding nonsense. Often in the same conversation.

Second, you’re deflecting ownership. “GPT said” is a subtle way of saying “don’t blame me if this is wrong.” But you’re the one who chose to bring it into the discussion. You’re the one presenting it. It’s your statement now.

Three Anti-Patterns

1. Citing the Oracle

“According to Claude, the best approach here is to use event sourcing.”

This carries zero weight. You can’t trace it. You can’t reproduce it - ask the same question tomorrow and you might get the opposite recommendation. There’s no paper, no documentation, no implementation behind it. It’s an opinion from a next-token predictor dressed up as expert advice.

If event sourcing is the right call, explain why it’s the right call. What are the trade-offs? What alternatives did you consider? If you can’t do that, you don’t understand the recommendation well enough to make it.

2. The AI Pass-Through

This one is sneakier. Someone gets feedback from a senior or peer engineer. Instead of thinking it through, understanding the concern, and responding with their own reasoning - they copy the feedback into an LLM chat or agent, then copy-paste the response back.

The result reads fine. Grammatically correct. Technically plausible. But it’s empty calories. The person never actually engaged with the feedback. They outsourced the thinking, not just the typing.

This is worse than the oracle pattern because it breaks the feedback loop entirely. The whole point of a code review or design discussion is that two humans reason together. When you insert an LLM as a proxy, nobody is actually thinking.

3. Stopping at Plausible

LLMs are extremely good at producing answers that sound right. That’s literally what they’re optimized for. And that’s exactly what makes them dangerous when you stop at “sounds right” instead of pushing to “is right.”

You ask Claude about a race condition. It gives you a confident explanation with a clean code fix. You paste it in, tests pass, ship it. Three weeks later it blows up in production because the LLM’s mental model of your concurrency setup was subtly wrong. It didn’t know about that one edge case in your custom executor. It can’t - it never saw your runtime.

The plausible answer was the starting point, not the finish line.

Validation Is the Actual Work

Using agents and LLMs to get answers faster is fine. Obviously. But faster access to candidate answers means the bottleneck shifts to validation. And validation is now your job.

Write a test. This is the easiest one. If an LLM tells you X is true about your system, write a small test that proves it. Ironically, the same AI tools are great at writing these validation tests - so use the agent to prove the agent isn’t lying. And honestly, this part is kinda satisfying. You can ask it to write a quick one-off script in whatever language - Python, Go, a shell one-liner - just to prove or disprove a single point. You look at it, run it, get your answer, and throw it away a minute later. Disposable code as a verification tool. Which is cool.

Ask for sources, then check them. LLMs can often point you to documentation, RFCs, or source code that backs their claim. But here’s the thing - when you actually ask “where did you get this?”, a decent chunk of the time you’ll get either a real reference you can verify, or a sudden “Actually…” Which tells you everything you need to know.

Read the code. AI tools are good at navigating and explaining source code. But don’t stop at the explanation - open the actual implementation, read it, run and debug. The code is the ground truth. The explanation is a hypothesis.

Cross-reference. If you’re making an architectural decision based on something an LLM told you, spend five minutes checking docs or other sources. If you can’t find independent confirmation, that’s a signal.

This Isn’t About Being Anti-AI

I use these tools constantly. They’re genuinely useful for moving faster, exploring unfamiliar codebases, generating boilerplate, rubber-ducking ideas. The productivity gains are real.

But there’s a difference between using a tool and hiding behind one. A calculator doesn’t make you a mathematician. An LLM doesn’t make you an architect. The value you bring is judgment - knowing when the output is right, when it’s subtly wrong, and when the question itself needs rethinking.

So next time you catch yourself reaching for “according to GPT…” or “Claude thinks…” - just don’t. If you believe the statement, own it. Explain your reasoning. If you can’t explain it without citing the AI, you haven’t done the work yet.

Agentic coding is the same. The tool is real. The manual is… crowd-sourced.

November 2025: The Inflection Point

The CLI agentic tools started appearing in early 2025. Claude Code launched in February as a research preview. Cursor shipped agent mode. OpenAI released Codex CLI. Aider had been around since 2023, quietly building a following. The tooling was ready.

But the models weren’t there yet. If you tried these tools in early 2025, results were hit-or-miss. Agents would confidently produce code that didn’t quite work, hallucinate APIs, or get stuck in loops. Andrej Karpathy captured the sentiment many developers felt: agents “just don’t work” because “they don’t have enough intelligence, they’re not multimodal enough” and “they’re cognitively lacking.” For many, autocomplete was the sweet spot - anything more autonomous felt like a dead end.

Then November 2025 happened.

Within weeks of each other, three major model releases landed: Claude Sonnet 4.5 (late September), Gemini 3.0 (November 18), and Claude Opus 4.5 (November 24). GPT-5.2 followed in December. These weren’t incremental improvements - they crossed a threshold. The models could reliably understand context, make coherent multi-file changes, recover from errors, and complete agentic workflows end-to-end.

The CLI tools that had been waiting for capable models suddenly had them. The shift happened, but it took a few weeks for people to notice. Most of us, myself included, only realized somewhere around Christmas that we had something fundamentally new in our hands. Not “better autocomplete” - a different tool entirely.

By the time the holidays ended, the reactions from people who’ve been writing code for decades started pouring in:

If you’re still skeptical, you’re out of step with where a lot of serious builders already are. The people above aren’t easily impressed, and they’re not selling anything. The shift is already underway. The question is whether you’ll adopt it intentionally or accidentally.

The Agent Loop

Forget magic. An agent is a while loop.

You give it a goal. It calls an LLM. The LLM either produces a response (done) or requests a tool call (read a file, run a command, make an API request). The tool executes, the result goes back to the LLM, and the loop continues. That’s it. No neural networks communicating telepathically. Just a loop.

while True:
  response = llm.call(context)
  if response.has_tool_call:
    result = execute_tool(response.tool_call)
    context.append(result)
  else:
   return response.text

If you’ve written a CI pipeline, a bash script that retries on failure, or a REPL - you already understand this. Same pattern: automated execution with feedback. The difference is the decision-making happens via LLM inference rather than hard-coded if statements.

All major vendors document this loop explicitly:

• Anthropic’s How Claude Code works describes it as a “single-threaded master loop” - while(tool_use) → execute → feed results → repeat
• OpenAI’s Codex agent loop documentation walks through the same pattern

The industry converged on this design because it works. Simple and debuggable.

“Isn’t this just Copilot with extra steps?” No. Copilot predicts your next few characters. Agents execute multi-step workflows - refactoring across files, running tests, fixing failures, iterating until tests pass. Different category entirely.

Typing Was Never the Job

Here’s something nobody told you in university: typing code was always a waste of time.

Think about it. CS programs teach algorithms, data structures, system design, discrete math. They don’t teach you to type faster. Why? Because typing was never the core skill. It was just… overhead. A necessary friction between the idea in your head and the running system.

We figured this out decades ago. Assembly programmers wrote one line per CPU instruction. Then we invented higher-level languages where a single line compiles into hundreds of instructions. Then we added frameworks, libraries, ORMs - each layer letting us type less while doing more. The entire history of programming is a march toward typing less. Agents are just the next step.

The best engineers I’ve worked with aren’t fast typists. They’re fast thinkers. They spend more time at whiteboards, in design docs, reading existing code - and less time with their fingers on the keyboard. The typing part was always the easy part. The thinking was hard.

Agents just made this obvious.

Where you spend time has fundamentally changed

Agents are extremely good at the mechanical parts of coding:

• Writing boilerplate
• Refactoring across files
• Navigating large codebases
• Applying patterns consistently

They’re bad at:

• Knowing what to build
• Understanding why something matters
• Making trade-off decisions
• Recognizing when requirements are wrong

The bottleneck moved. It used to be typing. Now it’s thinking.

This has a practical implication: the few minutes you spend thinking before opening an agent session will save hours of cleanup. The agent will happily generate 500 lines of code that solves the wrong problem. Faster.

You’re the Tech Lead Now

Agents don’t replace developers. They behave like very fast, very junior, very confident engineers who never push back, never ask clarifying questions, and never tell you your requirements are wrong.

Sound familiar? That’s a junior dev who needs supervision. Except this one types at 10,000 words per minute.

Your job changed. You now:

• Define intent and scope
• Break down work into digestible pieces
• Review outputs critically
• Correct direction when it drifts
• Make judgment calls the agent can’t

That’s tech lead work. Every developer working with agents is now managing a tireless but context-blind junior. The question isn’t whether you can code faster - it’s whether you can think clearly enough to direct that speed productively.

There’s an old IBM training slide from 1979:

Replace “computer” with “agent” and nothing changes. Agents are tools, not authors. You’re still accountable for what gets committed.

This matters because agents are genuinely bad at things that require judgment:

• Understanding product intent (why are we building this?)
• Evaluating architectural tradeoffs (is this the right abstraction?)
• Recognizing non-obvious constraints (will this scale? Is this secure?)
• Considering long-term consequences (how will this affect the codebase in a year?)

They optimize for local correctness and surface-level patterns. They’ll write code that compiles, passes the tests you gave them, and completely misses the point.

Human judgment remains irreplaceable: defining what matters, rejecting wrong-but-working solutions, keeping systems coherent over time. AI makes it trivially easy to produce code you don’t understand. This is technical debt in its purest form - you’ll pay for it during debugging, maintenance, and every code review.

“Won’t this destroy code quality?” Only if we let it. Agents don’t remove responsibility - they concentrate it.

Work in Phases, Not Prompts

Here’s the mistake most people make: they treat agents like a chat interface. Type a prompt, get code, paste it somewhere. That’s not agentic coding. That’s autocomplete with extra steps.

Real agentic work is phased. You don’t write a novel in one sentence, and you don’t build software in one prompt. The phases matter because they force you to think before generating, and because agents perform dramatically better when you separate concerns.

The four phases:

1. Problem Definition

Before touching any code, clarify what you’re actually building. This happens in a separate conversation or an explicit “planning mode.”

I need to implement [feature]. Here's the context:
- Current state: [what exists]
- Requirements: [what it should do]
- Constraints: [performance, compatibility, security]

What are my options? What trade-offs should I consider?

This phase is cheap. A few minutes of thinking. The agent helps you explore the problem space, surface edge cases you hadn’t considered, identify risks early. No code written yet.

2. Design Refinement

Once you have options, interrogate them. Push back. Ask hard questions.

Option B looks promising. But:
- How would this handle [edge case]?
- What's the failure mode if [scenario]?
- How does this integrate with [existing component]?

This is iterative. The agent proposes, you challenge, it refines. Still no implementation. You’re building a mental model and a shared understanding of what “done” looks like.

3. Implementation

Only now do you write code. And critically - you write it with explicit constraints from the previous phases.

Let's implement the approach we discussed. Starting with [component].
Key decisions we made:
- [Decision 1]: [rationale]
- [Decision 2]: [rationale]

Do not deviate from these without asking first.

The agent has context. It knows what you decided and why. It’s not guessing anymore.

4. Review & Validation

Never accept generated code blindly. Review the diff. Run the tests. Verify it actually does what you discussed.

This is also where testing happens. Some prefer test-driven development - writing tests before implementation. Either way, you need to be explicit with agents about testing:

Write tests for [component]. Specifically:
- Test [happy path scenario]
- Test [edge case 1]
- Test [error handling scenario]
- Mock [external service] - don't hit real endpoints
- Use real [database/cache] - no mocking for integration tests
- Do NOT test [implementation details that might change]

Agents will happily generate 50 tests that all test the same thing, or mock everything including the code you’re actually trying to verify. Be specific about what to test, how to test it, what to mock, and what should stay real.

This is where most time savings evaporate if you skip phases 1-3 - you end up debugging code you don’t understand that solves a problem you didn’t fully define.

These phases aren’t bureaucracy. They’re how you turn a chaotic code generator into a reliable collaborator. Skip them and you’ll spend more time fixing agent output than you saved generating it.

Prompts Are Contracts

Prompting is API design, not conversation.

Think about what makes a good API: clear inputs, defined outputs, explicit constraints, predictable behavior. Bad APIs accept anything and return surprises. Good APIs are strict about what they accept and consistent in what they return.

Same with prompts. “Fix this bug” is a bad API - undefined input, no constraints, unpredictable output. “This endpoint returns 500 when the user ID is null. Here’s the error log and the handler code. What’s causing this and what are my options?” is a good API - scoped input, clear context, defined expectation.

The difference in output quality is dramatic. Vague prompts produce vague code. Specific prompts produce specific solutions.

A few principles that help:

Scope aggressively. Don’t let agents roam freely across your codebase. Tell them exactly which files to touch and which to leave alone. “Modify only src/handlers/payment.ts” beats “fix the payment flow.” Smaller blast radius means easier review and fewer surprises.

Make constraints explicit. Agents don’t know your conventions unless you tell them. “Use our existing error format from src/errors.ts” or “Don’t add new dependencies” or “Keep the public API unchanged.” These aren’t obvious to an agent looking at your code for the first time.

Define what done looks like. “Implement caching” is ambiguous. “Add Redis caching for the /users/:id endpoint with 5-minute TTL, using our existing Redis client in src/infra/cache.ts” is actionable. The agent can verify its own work against concrete criteria.

Separate concerns. Avoid implementation and tests in the same prompt. The agent will write tests that pass its own code - which tells you nothing. Generate code, review it, then separately ask for tests with explicit guidance on what to cover.

“What about security?” Same as any automation. Scope, permissions, review. The danger is pretending agents are harmless because they feel conversational.

The Agent Instructions File

The instructions file (AGENTS.md, CLAUDE.md, .cursorrules, etc.) is the single most impactful thing you can optimize. This file affects every interaction the agent has with your codebase. A well-crafted file multiplies the effectiveness of every prompt you write.

Global Instructions

You should define global instructions that apply across all your projects - personal preferences, coding style, behavioral defaults. These are “how I work” regardless of what codebase I’m in.

# Global Instructions

## Communication Style
- Write as if talking to a peer engineer
- Avoid filler, hype, or disclaimers
- Ask for clarification when context is ambiguous
- Don't restate the obvious

## Coding Conventions
- Keep code clean and modular, but aim for simplicity
- Add comments only for unusual logic or rationale
- Always include type annotations
- Assume every project has linter and styling rules

## Architecture Principles
- Prefer composition over inheritance
- Use dependency injection for testability
- Adhere to SOLID principles

## Behavioral Defaults
- Prefer compact answers unless detail is essential
- When adding tests, always find a way to run them
- Keep documentation in sync with code changes

Project Instructions

Project files layer specifics on top - “how this codebase works.”

# Project: my-service

Backend service handling payment processing.

**Tech Stack:** Node.js 22.x, TypeScript, Express, PostgreSQL

## Development Setup

npm install
docker-compose up -d # starts Postgres
npm start # runs on port 4024

## Testing

npm test # runs all tests (requires Postgres)
npm test -- path/to/file.spec.ts # single file

## Architecture

### Entry Points

1. **REST API** - Handler: `apiHandler`
2. **Event Consumer** - Handler: `eventProcessor`
   - Trigger: SQS messages from `payments-queue`

### Key Patterns

- All handlers use dependency injection via constructor
- Database access only through repository classes
- External API calls wrapped in circuit breakers

## Conventions

- Error responses use RFC 7807 format
- All amounts stored as integers (cents)
- Timestamps in UTC, ISO 8601 format

Treat both as API contracts for agents. Changes should be intentional and reviewed, just like code.

Context Management

A critical insight: context degradation begins around 70% usage, not at 100%. Long conversations lead to:

• Forgotten earlier instructions
• Contradictory suggestions
• Repeated mistakes you already corrected
• Declining code quality

Signs your context is degraded:

• Agent forgets constraints you stated earlier
• Suggestions contradict previous decisions
• Quality noticeably drops from earlier in the conversation
• Agent starts “looping” on the same approaches

Strategies

1. Scope Conversations Tightly

One task per conversation. Don’t let sessions sprawl across unrelated concerns.

• Good: “Implement the payment validation endpoint”
• Bad: “Let’s work on the payment service” → then drift through five different features

2. The Copy-Paste Reset Technique

When context is degraded but you have useful progress:

1. Ask the agent to summarize the current state, decisions made, and remaining work
2. Start a fresh conversation
3. Paste the summary as your opening context
4. Continue with a clean context window

This gives you the benefits of accumulated progress without the degradation.

3. Use External Memory

Don’t rely solely on conversation history. Externalize important decisions:

• Update your instructions file with new patterns or constraints discovered during work
• Maintain a scratchpad file for complex multi-step tasks
• Document architectural decisions in your design docs

When You’re Stuck

If you find yourself:

• Asking the same question multiple ways
• Getting similar unhelpful responses
• Watching the agent repeat the same mistake
• Feeling frustrated with the output

You’re in a loop. Don’t keep iterating - change your approach.

Breaking Out:

1. Clear and Restart - Start a fresh conversation. Rephrase your goal from scratch. Often the accumulated context is the problem.

2. Simplify the Problem - Can you solve a smaller version first? Can you isolate the confusing part? Are you asking multiple things at once?

3. Show, Don’t Tell - Instead of explaining what you want, show an example. Provide a working snippet and ask for something similar.

4. Reframe the Problem - Instead of “how do I fix X” → “what are the possible causes of X”. Instead of “implement feature Y” → “what’s the simplest way to achieve Y given these constraints”.

5. Change Tools - Different LLMs have different strengths. If one isn’t working, try another.

The Title, Revisited

Agents are fast. That part is obvious now. They’ll generate code faster than you can read it, refactor entire modules in seconds, and never complain about tedious tasks.

But speed without direction just gets you lost faster.

The title of this post isn’t “Agents are fast, isn’t that great?” It’s “Agents are fast. You’re responsible.” The period matters. These are two separate statements. The first is a fact about the tool. The second is a fact about you.

Everything I’ve described - the phases, the contracts, the instructions files, the context management - exists to bridge that gap. To turn raw speed into directed progress. To ensure that when code hits production, someone understood it, validated it, and chose to ship it.

The tools will keep getting better. The models will keep improving. What won’t change is accountability. You’re still the engineer. You still own what gets committed. The agent is just a very fast, very eager collaborator that needs clear direction and constant supervision.

Use that speed wisely.

Design docs get a bad rap. Some teams treat them like bureaucratic overhead, others like sacred scripture that must be followed to the letter. Both miss the point.

The real purpose of design documentation isn’t uniformity or process compliance. It’s about articulating, sharing, and refining ideas before you start writing code. Whether that’s a 10-page spec or a whiteboard sketch - the format matters less than the thinking it forces you to do.

These documents - whether a brief outline, a structured specification, or simply a whiteboard sketch - serve to capture core objectives, constraints, and anticipated challenges early on. This proactive approach improves alignment, reduces misunderstandings, and ultimately increases the quality of the end product.

Why Bother?

The cost of fixing mistakes grows exponentially as a project moves through its lifecycle. Code Complete famously illustrates this with the “cost of mistake” curve:

Cost multipliers for fixing defects found at different phases (from Code Complete)

A requirements mistake caught during requirements costs 1x to fix. Catch it post-deploy? That’s 10-100x. Design mistakes follow a similar pattern. Design documents act as an early safeguard - catching issues before they multiply in cost and complexity. Nothing fancy here.

When to Write One

Not every task needs a design doc. Here’s when it actually helps:

1. New Features or Major Enhancements. Documenting the design clarifies functionality, dependencies, and architectural impact. The trigger is obvious, but some folks skip this step and regret it later.

2. Complex Dependencies or Cross-Team Integration. Features that touch multiple teams or rely on external systems need extra clarity. A design doc helps map out dependencies, integration points, and cross-functional impacts. Reduces last-minute surprises.

3. Significant Refactoring. Major refactoring efforts - especially those impacting core architecture or shared components - benefit from documented objectives and anticipated outcomes. It also lets teammates discuss alternative approaches before anyone writes code.

4. Technical Challenges and Unknowns. POCs, feasibility studies, creative problem-solving under constraints. A design doc becomes a platform to hypothesize solutions, evaluate feasibility, and gather feedback. Particularly valuable when choosing between multiple approaches.

5. High-Impact or Customer-Facing Changes. Anything that directly impacts user experience or has high bug risk. Design documentation helps anticipate issues and evaluate risks upfront.

When to Skip It

Sometimes the design you create in your head is enough. What matters is that you’ve thought through the approach before diving in.

Design docs are overhead. If the task is small, well-understood, and unlikely to benefit from broader discussion, skip the doc. For trivial fixes, minor tweaks, or isolated refactoring - just write good comments in your code explaining the reasoning.

When it reads like an implementation manual. If your design document feels like step-by-step instructions, stop. Break the work into tickets instead. Design docs should focus on “what” and “why”, not granular “how”.

Known problems. For routine problems already solved repeatedly in similar ways, just refer to existing templates or past solutions. Don’t duplicate effort.

Types of Design Documents

Three practical options:

1. High-Level Overview. For early brainstorming or stakeholder alignment. Captures main goals, constraints, and basic technical direction. No formal structure needed - its purpose is capturing and communicating key ideas. This is probably the most common type. Typically 3-7 pages, balancing clarity and detail. Good enough for most scenarios.

2. Detailed Design Specification. When technical depth or cross-team coordination is essential. Includes specific functional requirements, architectural considerations, and diagrams for complex data flows. Follows a more formal structure.

3. Whiteboard Sketch or Quick Diagram. Sometimes a photo of a whiteboard is all you need. Great for simple tasks or ideation sessions. Less formal but effective for getting ideas across quickly.

💡 The goal is to make documenting your design simple and approachable. Choose the type that fits your needs. There’s no rigid template.

Writing Good Design Docs

Start with the Problem. A good design document starts with a clear articulation of the problem, the context, and why it matters. If product requirements exist, translate them into technical terms:

• Product Requirement: “Users should be able to see their recent transactions instantly.”
• Technical Problem Statement: “Design a low-latency API and caching strategy to retrieve and display recent transactions within 200ms.”

Clarity Over Perfection. A design doesn’t need to be perfect - it needs to be understandable. Focus on communicating core ideas, key decisions, and trade-offs. Use simple terms and visualize whenever possible, even if you feel uncomfortable drawing. Diagrams and flowcharts often communicate complex ideas more effectively than text.

Provide a High-Level Overview. Focus on which parts of the system will be created or modified and how they relate to each other. Prioritize logical relationships over technical details like protocols or database types.

Example: High-level system diagram showing component relationships

It’s also valuable to include a System Context Diagram showing how the solution fits into the overall platform:

System Context Diagram - shows interactions between your solution and external systems

Document Key Decisions and Trade-offs. A design isn’t just about “what” you’re building but also “why”. Capture the reasoning behind major decisions, including alternatives you considered and why you rejected them.

For example:

• Decision: Cache the last 50 transactions per user in an in-memory store
• Trade-off: Improves API response time but introduces stale data risk if cache invalidation is delayed
• Alternative Considered: Query database directly for each request. Rejected due to performance degradation under heavy load.

💡 Every decision involves a trade-off. Capturing these ensures transparency and avoids revisiting the same discussions later.

Consider Your Audience. Some designs are reviewed by deeply technical teammates. Others need to be presented to product teams or stakeholders with minimal technical background. Tailor accordingly.

Iterate. Don’t aim for a complete final document on your first try. Begin with a rough draft, refine based on feedback. Share for feedback once the main idea is communicated clearly - not while it’s half-baked. Think through potential challenges reviewers may raise and address them preemptively.

Design documents are living artifacts. Update them as the project evolves or new decisions are made. They should remain a reliable source of truth throughout the project lifecycle.

References

Books and Articles

• Code Complete by Steve McConnell - practical advice on software construction
• Designing Data-Intensive Applications by Martin Kleppmann - system design challenges and trade-offs
• Martin Fowler’s Architecture Decision Records - documenting architectural decisions effectively

Online Resources

• System Design Primer (GitHub) - system design resources and examples
• AWS Well-Architected Framework - best practices for scalable cloud systems
• Google’s Site Reliability Engineering Guide - engineering reliable systems

Diagrams and Visualization Tools

• Lucidchart, draw.io, WebSequenceDiagrams - clear, shareable visuals
• C4 Model - lightweight approach to architecture diagrams focusing on clarity and hierarchy

Case Studies

• Uber Engineering Blog - large-scale system design challenges
• Netflix Tech Blog - architectural patterns and trade-offs at scale
• High Scalability - real-world architectural examples

This is sort of the second part of the post I wrote a while ago about building JavaScript widget. To my surprise, I received a lot of valuable feedback and some questions on how to deal with some specific scenarios:  

• How to use it with UI framework (e.g. React or Angular)
• What is the best way to manage configurations
• How to serve multiple instances from the same page
• How the deployment of such thing looks like

Those are all valid questions. So the idea here is to extend the original example and make from it an actual deployable widget:

Widget that is shown on bottom right of the page (it may look dark if you are into dark theme)

Go ahead and play around with this. This is the most basic example I came up with and it has:

• Basic form with validation
• Some list that fetched from remote endpoint
• A concept of multiple views/pages
• Styles that are responsive for viewport and dark/light themes. A couple of SVG icons and yet everything is loaded in a single round trip to CDN.

Like in original post, same non-functional requirements apply:

• A hosting website shouldn’t be affected by adding the widget. It cannot negatively affect page load latency and performance in general. It may not conflict with existing code and styling of the page. In fact, the result you are seeing on this page is under 30KB and served in a single request (including embedded SVGs).
• The embeddable snippet must be simple to integrate, hard to make mistakes while embedding it, but allow to extend the functionality or change the look of the widget.
• It should be a joy to develop while supporting (with certain trade offs) to wide versions of browsers.

Application

Now that it is clear what is the end result, let’s take a look on the building blocks of our code:

So, there are basically 2 parts - the installation script on the left side of the diagram and the widget application itself on the right side.

Installation Script

I wrote in details why it looks like this here, so it is basically the same thing with a minor changes:

The highlighted parts are:

• In red is the instance name. It only matters when a multiple instances of the widget needs to be loaded into a page, then each instance requires a unique name. This way it allows us interact (initialize settings and call methods) with the specific instance.
• In yellow is the method to execute in a widget. init is a special method and the only one required to “start” widget. There can be other methods (not in my example) called immediately or much later, which is the way to interact with the widget.
• Optional parameters are in green. init method’s parameter has a defined structure which “configures” the widget.
• And in blue we have a full URL to the location where the widget is hosted. In some cases site owners prefer to host the widget in different location (e.g. under their own host name), but this obviously means they will lose updates of the widget that will be pushed to CDN.

Widget Application

The source code of the widget that you see on this page is located at this git repository. This is a fairly standard client-side application written in TypeScript. It is not far away from my original example, except that this time I took the example all the way to be more realistic in terms of functionality and “deployability” (I may have invented this word just now).

Please take into account that although the widget is fully functional, it is still for demonstration purposes and you should adjust it to your production realities.

Skeleton If I peel all UI and state management from it, you will find the main difference of this application from other client-based applications - the main entry point to the application, AKA static void main() in other well known languages.

The module that handles loading of the application is /src/loader.ts, which consist of:

• Figure out the instance name (there can be multiple instances). The trick for this part is that the installation script will place an id attribute to script tag with value being unique name of the widget’s instance. Later on, when the widget loads it will get a hold of the “current” instance name via instance of script tag by using  document.currentScript API.
• Start processing all methods that were called while widget.js was asynchronously downloaded (basically those that are called in the installation script). One of those methods is init, which is where we start our “rendering” (or not, if the widget is UI-less).
• Store indication that the instance was “started”. The purpose of this is to prevent accidental multiple initializations of the same instance.

Note, currentScript is totally unsupported by IE11 (funny thing that it does in older versions of IE). This means that multi-instance of a widget with this implementation won’t work in IE11. There are ways to solve it, but I’m leaving it out of scope of the article.

Adding UI I decided to use Preact, because it’s just insanely small, which is really important for the widget. But nothing prevents you from using any other UI library.

If you are not familiar with Preact, it is basically React with the same JSX syntax, but much smaller because it doesn’t implement all features that React has.

Once we reach up to App.tsx, you will find a React-like application which leverage Context for global state, Layout to hold a common components, “pages views” which are loaded via a light in-memory router:

Widget application structure

I intentionally decided not to use preact-router, because it adds event listeners to all anchors on document level, which is not acceptable for widget (remember not to mess with the hosting page). Since this router doesn’t use any shared resource of the page (e.g. URL, history, document event listeners), it’s scoped nicely to a single widget instance.

The last thing that is worth mentioning is an extensive usage of CSS modules. You will find the “main” styles in  /src/layout/main.css, which also has styles-reset which should prevent page’s styles from affecting the widget. This reset is fairly basic, and if you are looking for more “aggressive” isolation from styles defined on a page, I would recommend Cleanslate.

Tooling As in a regular node.js application, you can start a widget in your local environment via  npm start, which will launch a demo HTML page /dev/index.html. The whole purpose of the page is to render the widget while developing it. The page contains an installation script, which embeds a version that is compiled from source each time changes are detected.

Everything that is related to building files, both for dev and release, into single-js-file is located in /webpack.config.js. This file contains similar configurations as in my previous post, except for the TypeScript compilation and instructions how to compile JSX via Preact.

Backend Interaction help-widget is also invokes REST remote APIs - sends contact form data and queries a list of FAQ questions. The backend itself is not interesting in scope of the widget. Yours probably will look very different in terms of language & runtime choice, persistence type, authorization, etc. But just for a sake of a fully functional example of the widget, I needed something simple, so I included it and it is hosted on Glitch.

Deployment

For this demo I decided to use AWS for hosting the widget and GitHub Actions for building and deploying it. There is nothing special in those two vendors to achieve the task, you can easily pick any other vendors, the concepts are pretty much the same.

Since the widget itself is no more than a static JavaScript file, I’m going to host it in S3 bucket and serve it via CloudFront - AWS CDN service. The way the file will get there, is that once we tag a particular commit in git, a workflow in GitHub’s Actions will grab the source, compile it and upload to AWS. The extended explanation of the same is on this diagram:

Workflows for GitHub Actions configured by adding files to /.github/workflows folder. Each file defines a workflow - ci.yml for build, release.yml for creating a new release and deploy.yml for uploading latest release to AWS.

ci.yml is pretty straight forward. Its whole purpose is to validate style and correctness of the code. It will be triggered on a new Pull Request, run lint, test & build and report the status back to Pull Request, so you can decide whether to merge the changes.

release.yml is triggered when a new tag is pushed. So, at some stage you decide that master branch is in a good shape to create a new version, thus you will tag it with tag in format of v*. For instance:

git tag v0.0.2
git push origin v0.0.2

The workflow then perform a build in “release” mode, which will output a single optimized JavaScript file, and attach the file as an asset to release:

Now that the release is persisted, a deploy workflow will be triggered.

deploy.yml is very specific to the hosting model I chose - AWS S3 with CloudFront. Most likely you will need to change it to your scenario, or all together drop, if deployment is handled manually.

The workflow downloads a newly added release, uploads the JS file to S3 bucket and calls CloudFront cache invalidation API. Invalidation is not synchronous, but once finished a latest version of the widget will be available through CDN.

The required resources in AWS for hosting the widget, can be created with AWS CloudFormation template similar to this one.

Summary

In this article I tried to cover all the missing parts from my previous post - the result is GiHub repository that contains all sources for  building and deploying a fully functional web widget.

The widget is built using TypeScript and Preact, deployed by GitHub Actions and hosted in AWS.

Source: The Gartner Hype Cycle for Emerging Technologies, 2017

There is also a huge amount of posts, books and videos about and how to “serverless”. You can literally drown in this amount of information without finding the essential parts.

I see many developers (including me not that along ago) either struggle with understanding which use cases it fits the best, or misuse it in such way, that it is near impossible to maintain.

My Golden Rules

While there are many guidelines that tries to cover all of the aspects of Serverless technology, I wanted to catch things that are most (or sometimes the only) things that important.

Below you will find essentials things to hold in your head while, or even before you starting, implementing application using Serverless mechanism.

Web interface trap

It is really easy to start with Serverless, while ignoring a few, or all, of the principles of software development for writing SOLID and clean code. For instance, both AWS and Azure allow to create functions directly from their web portals. Very easy to start. But man, oh man, your colleagues won’t thank you later. Maintenance, team collaboration, testing and code sharing with this approach are very challenging.

So rule #1 try to avoid creating function from the web interface, unless it is something you want to play around or you know that the lifetime of the function will be short.

Minimal work

Each function should do as minimal work as possible. This is intentionally the second rule. While in “normal” application this is obvious to all of us, in Serverless people tend to abuse a single function.

An example will be appropriate now :) Let’s say you need to call some API after a message arrives to a queue, and store the result in database. You can do it all in single function, and there might be cases when it makes sense, but I would suggest to break it apart into 3 separate functions (just like you will do in a “normal world”):

• First function triggered by a message in that queue. It will parse the message, may be filter out, may be reduce several messages into one operation. Once done, call next function (usually by placing a message to another queue).
• Next function will call 3rd party API (whether it is HTTP, RPC or something else). After it gets OK from this API, it can pass the result of the API call to the next function
• The last function will write to database the result

It is very simple - every function handles something very specific and no more than this. If you are straggling to brake a part the functionality into small peaces, it might be a sign that Serverless is not the best platform for the use case. Don’t give up quickly - there are a few tricks on how to break apart parsing huge file, processing mbillions records, paging through large datasets with continuation token, etc..

Functions should form applications

Functions should be grouped into applications (some unit of logic). Usually you won’t be writing a single, stand alone function. I mean there are exceptions, but in most cases you ended up having a set of functions which can be merged into single logical group with shared code.

This group then can reside in dedicated git repository, like a “normal” application, and deployed as a single unit, again, like a “normal” application. All platforms allows grouping functions into some sort of applications.

Once you start threating functions as applications, then it suddenly sounds obvious that they must have code reviews, CI, tests, documentation, monitoring and release management.

Idempotency

In best scenario the function should be idempotent (it is not always possible, especially when dealing with 3rd party APIs). Serverless runtimes have automatic retry policies in case function didn’t succeeded (unhandled exceptions, timeouts or out of memory). So if the function is idempotent, it will play nice with runtime - executing multiple times without creating side effects in your application.

In some cases it can helpful to use requestId/InvocationId/CorrelationId , which is supplied by a runtime on each call. If it is a retry operation, the identifier will be the same and it will allow you to detect whether the invocation already happened before.

The same correlation identifier you will find attached to log messages, which is very helpful to isolate message from one invocation to another

References:

• AWS retry policy
• Azure retry policy
• AWS requestId for Node.js (similar to other languages runtimes)
• Azure InvocationId

Running time constraint

It is important to remember that there is a limit of how long the function can be running. There is a stopwatch that started once the function called, and if it reaches the limit, then your function will be terminated.

This, again, may raise the question whether the Serverless fits your use case - you cannot process a huge amount of data in single invocation, unless you measure the running time and can “pause and resume” processing.

Some platforms have an option to eliminate this limitation, but then is it still Serverless where you pay per invocation?

For instance, when dealing with huge files, think how to break it a part with offsets. If you to process a large amount of records, then probably each invocation should deal with a single or few records each time.

Bindings and triggers

IMHO this is one of the main selling points of Serverless - bindings and triggers.

Bindings is pretty unique feature in Azure

It is really allows you to concentrate on the business logic and not plumbing. Instead of hosting web server, writing queues consumer, writing poller for incoming files/records, figuring which scheduler to use, the runtime takes care for it:

It also easy to switch between triggers - you have one logic that triggered by message in queue today, and tomorrow you easily convert or add to it HTTP endpoint.

While being one of the main features, this is also one the main limitations. You end up designing the solution around the available triggers, which in some cases may be just not possible. If you need to write a consumer for Kafka in AWS Lamda, or Azure Function that triggered by new message in RabitMQ, you are out of luck. There are solutions, but they usually either involves some middle tier or polling with scheduled functions, which in my opinion kills the concept of Serverless.

Function body

The body of the function itself should not do a lot. Think of it as static void main() - you don’t write your logic there, you parse args, construct your service/s and invoke them. This way you will be also able to “unit” test your service alone, not that you always should.

There are toolings that allow you to execute functions locally (serverless, Azure Func CLI to name a few) and write a full integration tests, but I still suggest to keep function’s body clean from business logic.

Decoupling business logic from runtime environment is usually a good practice to follow. Not that it should be your guideline, but think how easily you can move your logic to non-Serverless platform (micro-service or monolith) or, may be even, other Serverless provider.

Exceptions are good

If there is something unexpected happened, you should throw exceptions as soon as possible. 3rd party API returned 429 or 503? Got transient error from db connection? Just throw - there is a retry policy in place, and eventually, after a runtime will give up on retrying it can place a message in DLQ.

If functions are small and do exactly one thing, then there is no reason to worry about exceptions being bubbled to many levels up.

If you find yourself writing or using library with complex retry with exponential backoff or something similar inside your function, ask yourself again whether the Serverless fits the use case.

Parallelism

This is also one of the main selling points of Serverless - horizontal scalability. You can control how “much of scale” you want per function. And you definitely need to be aware of it and use it, because for certain scenarios functions have insane defaults and may do you bad:

• Databases has limitation on active client connections, so you won’t be able to write in parallel with infinite amount of function instances
• If you are going to call 3rd party API at a rate of 1000 req/sec you probably will be banned
• If you are going to call your own service at this rate, it can just end up in DoS
• Crawling websites at high rate, may take them down, or if they are behind services like Cloudflare, you will be storing reCAPTCHA challenge in your database

If we follow the example from above with 3 functions, then you have a control at which rate each thing happens really easily - no limit for reading from incoming queue, 10 for calling 3rd party API and 5 for inserting records to DB. And obviously you will need to monitor queues to understand where and if a bottleneck happens.

Another example, if there can be only single reader of huge file, you limit the parallelism to single instance of the reader, but the data processors may have infinite scale.

Summary

By following the rules above, I was able to deploy a large amount of Serverless applications and maintain it happily with other team mates. But the most important, that those rules prevented from me in some cases to use Serverless technology, as it was just not a good fit and probably would end up badly product and cost-wise.

For the widget to be successful there are a few really important non functional requirements:

• Widget’s code should never ever mess up with the site it being hosted on. Think isolation.
• It should support the whole spectrum of browsers that users of the sites may use. Think IE6.
• It should not affect (or have a minimum impact on) performance of the website. Think small and async.
• You cannot rely on any library or it’s specific version presented on a site. On another hand, the library you are depending on can be already loaded on the site. Think noConflict().

TLTR;

The end result of what we build here is located here. This is some sort of template for creating JavaScript widget with HTML and CSS in which I find comfortable to develop and easy to deploy as single small JS file.

The embeddable part

This is the block of code that the website owner will need to embed on his/her website. This code block must have a smallest possible footprint. If it will be large, it may just scare out site owner.

So the obvious that many other articles suggest is to have something like this:

<script src="https://widget.com/script.js" type="text/javascript"></script>

A few problems with this approach:

• It is blocking. You can fix it with async attribute if you care of IE 10+ only.
• You don’t control the location of the script within HTML document - it is up to the site owner where he will place it.
• If you need some additional configurations you will need to add an additional script block, which makes it less solid and may lead to confusion, forgetting one of the parts (not all site owners are technical people), mixing their order, etc.:

<script src="https://widget.com/script.js" type="text/javascript"></script>
<script type="text/javascript">
    widget.settings({someParam: true});
</script>

Basically those are reasons why Google Analytics, Facebook SDK and other vendors with high JavaScript SDKs usages ended with something similar to this:

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
  ga('create', 'UA-XXXXXX-XX', 'auto');
</script>

The code above solves all 3 issues I mentioned above plus a few extra cool things. Here the same code which I un-obfusticated and added explanations:

The script creates isolated scope via self-evaluated function which is important in order not to collide with others on the page. The last line is the configurations that site owner may add (e.g. UI, behavior, etc.) and the one line before this (parameters that passed to the method) are kinda “advanced” configurations for developers.

Now that we have a good understanding of how the implantation should look like let’s create something similar:

(function (w,d,s,o,f,js,fjs) {
    w['MyWidget']=o;w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments) };
    js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];
    js.id = o; js.src = f; js.async = 1; fjs.parentNode.insertBefore(js, fjs);
}(window, document, 'script', 'mw', '//SOME_CDN/widget.js'));
mw('init', { showButton: true });

You will find this script located in demo page, which simulates client’s site and we’ll use it for development purpose.

Application Structure

Widget application is what will be loaded and executed by the embedded script on site. It may have different degree of complexity, but for any use case it should:

• Have a good structure for separation of concerns and test-ability, which means proper module loading
• Convenient development experience via hot-module reloading

I’ll use WebPack to address requirements above, but first let’s finalize the structure of the app:

It’s pretty common structure for JS application. Code goes into src and the entry point is main.js. The demo folder contains an emulated site’s page we talked before, it is also the page that we’ll serve by local dev server to develop widget application.

Let’s start with simple main.js:

import { ping } from './services'

function app() {
    console.log('JS-Widget starting');
}

app();

Our main function is app() which evaluated as soon as this module loaded. Also note that I’m using here ECMAScript 6 module loading, which allows us to separate and isolate different parts of application.

Building and running

The next step is to build and able to serve the app to browser. As I mention, we’ll use WebPack and we’ll need the following packages:

npm install webpack webpack-dev-server copy-webpack-plugin --save-dev

What I want to achieve is that WebPack will take the whole application with all its modules and produce a servable single file which will be loaded in demo/index.html file. For this to happen I need to add webpack.config.js file in root with the following configuration:

const path = require('path');
const webpack = require('webpack');
var copyWebpackPlugin = require('copy-webpack-plugin');
const bundleOutputDir = './dist';

module.exports = (env) => {
    return [{
        entry: './src/main.js',
        output: {
            filename: 'widget.js',
            path: path.resolve(bundleOutputDir),
        },
        devServer: {
            contentBase: bundleOutputDir
        },
        plugins: [new webpack.SourceMapDevToolPlugin(), new copyWebpackPlugin([{ from: 'demo/' }])]
    }];
};

Note how we instruct WebPack what is the entry of the application - main.js, so it can traverse it and produce a single file in dist/widget.js. There are also 2 plugins to allow mapping of source code for debugging, and copying the index.html into build destination. The last interesting thing here is devServer section which instructs local HTTP server to serve the dist folder.

To build let’s run:

 ./node_modules/.bin/webpack --config webpack.config.js

and check the result in dist folder.

Now, let’s serve it:

./node_modules/.bin/webpack-dev-server --open

Once browser is launched, go to the browser’s console and you should find JS-Widget starting log entry, which means the application (widget) was loaded.

At this stage you will be able to develop the application (adding and modifying JS files) and the webpack-dev-server will auto-reloaded those modules in your browser.

Building release

First of all we need to differentiate between build types. We’ll do it by passing argument --env.prod to BuildPack:

./node_modules/.bin/webpack --config webpack.config.js --env.prod

and inside webpack.config.js file we’ll be able to “catch” it:

module.exports = (env) => {
    const isDevBuild = !(env && env.prod);
    ...
};

The second thing we’ll want to do is to minimize the output. This is done by adding UglifyJsPlugin plugin for non-dev build:

    module.exports = (env) => {
        const isDevBuild = !(env && env.prod);
        ...
            plugins: isDevBuild
                ? [new webpack.SourceMapDevToolPlugin(), new copyWebpackPlugin([{ from: 'demo/' }])]
                : [new webpack.optimize.UglifyJsPlugin()]
        ...
    };

Now we can run build with release parameter and you will get combined, obfuscated and minimized JS file in dist folder.

The next phase is to be able write code in modern version of JavaScript (e.g. ECMAScript 6) and during build transpile it down to code that can be executed in, let’s say, IE6. This is where Babel comes into the picture. We’ll need the following dependencies:

npm install @babel/core @babel/preset-env babel-loader@next --save-dev

and then, again, let’s change the webpack.config.js. The babel is added as module to WebPack, which allows to manipulate the intermediate result before it’s written to the output:

module.exports = (env) => {
  ...
  module: {
    rules: [
      {
        test: /\.js$/i, exclude: /node_modules/, use: {
          loader: 'babel-loader',
          options: {
            presets: [['@babel/env', {
                'targets': { 'browsers': ['ie 6', 'safari 7'] }
            }]]
          }
        }
      }
    ]
  }
  ...
};

Note how we target specific browsers instead of version of JavaScript, which is much more convenient.

Adding HTML and CSS

Some widget may have UI components in them, those much easier to construct by using HTML markup and CSS. But, again, we want to have a minimal footprint in network - not to load additional files. The ideal will be to combine CSS and HTML in to the same JS file.

There is, however, one down side that you need to be aware of. In this solution the CSS is not isolated from the rest of the styles on page - it’s injected into the page itself under dynamically added style tag. The HTML is also may be affected by styles on the page, unless you will be appending it into iframe tags, which has it’s own downsides.

There is much robust solution to a CSS and HTML isolation - Shadow DOM, but unfortunately the browsers support of such feature and nature of JS widget don’t play well together.

Let’s see how we can do it. We’ll leverage again WebPack’s modules. The following packages required:

npm install css-loader html-loader style-loader --save-dev

and in webpack.config.js add in modules the following:

module.exports = (env) => {
    ...
    module: {
        rules: [
            { test: /\.html$/i, use: 'html-loader' },
            { test: /\.css$/i, use: ['style-loader', 'css-loader' + (isDevBuild ? '' : '?minimize')] },
    ...
};

Note how those modules targeted by css and html extensions of files. The rest is standard ES module loader. I added HTML with CSS files and the JS module just importing those files:

import template from './message.html';
import './message.css';

The template variable will contain a string representation of the HTML “template”, which needs to be converted to HTML Element and appended to page document.

External librarires

The widget itself has no external runtime dependencies. This guarantees a minimal footprint. It doesn’t mean you cannot use external libraries, but should use and load them responsibly - load asynchronously and avoid conflicts with site’s frameworks.

Another thing to consider is that may be the library you are depending on is already presented on the hosting site. jQuery for instance still has a high usage. Take a look at this example on how to load jQuery without conflicting or alternately use already loaded jQuery.

It is probably worth mentioning that relying on Angular in most cases will be an overkill. Most widgets have single or, at top, a few views, so it wiser to rely on something much compact (e.g. Vue.js).

Summary

We had built something that can be used as good start for developing JS widget that can be deployed to other websites. We didn’t compromise on development experience and used a modern tooling with modern language features, but still were able to target old browsers.

You can find all source code of the widget here.

Update May 2020

I wrote a second part of the article, which go further in implementing the UI widget and explains a deployment scenarios. You can read it here.

In this project-for-fun me with co-workers decided to build a small system which will leverage Emotion API to get some insights on how people feel during the work.

The setup

In the office we installed RPi board with camera. The location of camera can be tricky, because we need to catch as many faces as possible during the day, and ideally different faces. The purpose of this part is to detect image with faces and once detected, the image is sent to the backend.

When an image arrives to the backend we’ll persist it, send it to Cognitive Service, store results and perform some additional image manipulations.

This pipeline allows us send a daily reports of who is the most happy, angry, etc. person and visualize aggregative data - how mood change during period of time, which are dominating moods and so on.

Obviously for us, we must try out other cool toys when building such project - serverless architecture, JS frameworks, 3D printing, IoT boards, etc.

Let’s dig into details.

The device

This device consists of 2 main components - Raspberry Pi and camera connected to it. It all packed into a nice box, which was modeled and printed by my colleague:

The camera located in the right eye of the owl, which allowed to place it near the door of central entrance to observe all people entering the office:

Here are few more shots of the device internals:

Device’s smarts

The device is not that smart, but is has some interesting part in it. What I wanted to prevent is to send the entire video stream outside the device. The optimal would be detect frames that may contain faces (AKA face detection) and send only them. This will save a huge amount of traffic to the backend. But it also means that device’s CPU should be fast enough to execute algorithm ideally 30 times per second.

It is currently RPi 2. It works kinda OK - there are some frames that dropped. The plan is to upgrade to RPi 3.

Face detection performed using OpenCV library. The unfortunate part is that there is no precompiled package of it for RaspberryPi, the fortunate part is that someone wrote thorough instructions for compiling from source for RPi.

The source code which running the board is located here. There are 2 types of workers:

1. Detector will analyze each frame using Haar Cascades Classifier and if face/s detected will push the image into in-memory queue
2. Sender will de-queue and send the image to the backend

Simple.

Backend

The backend job is to execute pipeline for each received image - receive, store, enrich, transform and expose. We implemented this pipeline using Azure Function. Each function will perform a smallest possible task and they will be connected using Queues and Topics of Azure Service Bus.

The building blocks of the pipeline when image received is self-explanatory and you can also find a flow diagram along with the source code here. The core part of detecting moods located in function SendToEmotion and its essentially sending the image to Azure Emotions API. Down to pipeline the results are persisted into SQL database so they can be later used for reporting and UI.

Exposing results

So we started with daily report via email that will show most happy, most angry, etc. people. There was no real value in it beside the fun part:

The next phase was to create a dashboard which shows how moods changes during period of time and aggregate it during time of the workday:

From this we came to conclusion:

1. People are usually more happy before breakfast and dinner
2. Sad (or tired?) after dinner
3. Angry on Sundays

There are a few more screens. The web client app source code is located here.

Summary

The end result is the system that aggregates people’s emotions and exposes those results via reports and dashboard.

We argued a lot whether there is a practical value in such system. For me personally this turned out to be a nice experience and allowed to explore some things that we are not dealing with day-to-day.

If you need to hide endpoints in Swagger UI based on authorization token, here is the repository with demo for .NET Core app. The relevant parts are passing HTTP header and filter for rendering schema based on permissions.

Swagger

Swagger described as API framework, but for me the most important part of it is an ability to describe in source code the API - endpoint URIs and methods, models of request and response, supported response HTTP codes and so on. There are obvious pros of doing it in source code.

This makes super-easy and fast to integrate between different applications/parties - consumer just need to look at Swagger schema or UI to get an idea on what to expect. No, it is not SOAP, but definitely has some similarity.

Visibility trimming

While many things comes out of the box in Swagger UI, including OAuth2 flows support for indicating which endpoints require authorization and triggering the flow, there was still one thing I missed in a few projects in a row.

Let’s say there are different consumers of the API, each with different scopes or roles. Usually you will leverage standard Authorize attribute, which will handle the authorization part of the endpoint when the API invoked, however this doesn’t prevent from client to see and inspect the endpoint to which he is not authorized. Swagger ignores the attribute, and displays all endpoints, regardless the user is authorized or even authenticated.

At this point I must say that this behavior, probably, in most cases is desired. Even for me, in many projects regardless the permissions of the client, I don’t mind, or even willing, to show all available APIs of the application.

So what we want to do is hide APIs that the user is not allowed to access.

Passing authorization token

Let’s start from the fact that we need to pass authorization token from Swagger to our backend.

In my example I’ll be using JWT token with JwtBearer middleware, but it should work with any type of authorization, as long as you relies on Authorize attribute.

In Swagger UI there is a field called ‘api_key’. Depending on version it may looks different and you may find it in different places. Here it is in version I used:

The out-of-the-box behavior of this thing is to append the value from this input to the HTTP header called api_key to every request that done when you click on ‘Try it out!’ button. Instead, we’ll take the value, prefix it with Bearer and put it into standard HTTP header Authorization. To achieve it, we need to change JS function located in index.html called addApiKeyAuthorization.

The page itself (where the function located) rendered by SwaggerUi middleware, thus we’ll need to override the page with static file in the same path. The important part for this trick to work, is that StaticFiles middleware must be registered before SwaggerUi middleware.

Once the file in under wwwroot/swagger/ui/index.html and the function has the following line:

var apiKeyAuth = new SwaggerClient.ApiKeyAuthorization("Authorization", "Bearer " + key, "header");

The token will be passed in all requests, including the most important for us - when the schema file swagger/v1/swagger.json is retrieved by Swagger UI.

Dynamic schema file

In order to produce a custom swagger.json we’ll add a custom IDocumentFilter:

services.AddSwaggerGen(options =>
{
    options.DocumentFilter<SwaggerAuthorizationFilter>();
});

The filter evaluated when a schema file is rendered. The main part is in Apply method:

• Loop through each endpoint method
• Collect Authorize attributes from action method and controller class
• If the attribute presented, check if user authenticated or, if policy specified, evaluate current user against the policy
• If user doesn’t pass check, hide method or the whole endpoint

Summary

By using extensibility of Swashbuckle we were able to intercept schema rendering of Swagger UI and expose endpoints that the user is allowed to view/use based on the specified authorization token.

Update February 2017

In original demo I used package Swashbuckle 6.0.0-beta901 which uses a version of Swagger UI that didn’t had an ability to customize authentication beyound passing api_key in query string. This is the reason for adding a custom index.html to override method addApiKeyAuthorization.

This is no longer true with the version Swashbuckle.AspNetCore 1.0.0-rc1, where the latest Swagger UI version allows to specify where to pass authorization token. This simplifies the implementation a little and I added example in the same repository side by side with the original demo.

Update May 2020

I added another example for Swashbuckle 5+, which uses Swagger UI v. 3+ and latest OpenAPI. It does essentially the same as in previous versions.

The Why

While probably the most natural cloud environment for .net core app is Azure, there is still a good reason why would you want sometimes to host on Heroku - you get a wide PaaS offering without headache (also called add-ons).

So, let’s say your app needs PostgreSQL, Neo4j, RabbitMQ or something from this list, IMHO it will be faster to spin up environment in Heroku. You can go and try find a vendor that will maintain one of those services for you in Azure’s data center, while in Heroku they all provisioned literally with button click and scaled by slider.

Enter Heroku

Currently there are 2 options to deploy an app into Heroku’s containers (also called dynos):

• Using Dockerfile, which is a pretty new in Heroku. There are some naming issues due to copyright, thus it’s called Container Registry and Runtime
• Using buildpack, which is similar to Kudu in Azure. The buildpack is responsible to setup a correct runtime for the application in container, build the application and provision it into container

Each option has its pros and cons. After trying both, I decided to stick with buildpack.

Prepare app

In both cases you need to be able to pass port to which the Kestrel will bind itself. This can be done either by setting environment variable ASPNETCORE_URLS:

ASPNETCORE_URLS='http://+:\8080' dotnet run

or by specifying via command line arguments:

dotnet run --server.urls http://+:8080

For command line arguments to work, add Microsoft.Extensions.Configuration.CommandLine package to the application and in Program.cs you should have something similar to:

public static void Main(string[] args)
{
    var configurations = new ConfigurationBuilder()
        .AddCommandLine(args)
        .Build();

    new WebHostBuilder()
        .UseConfiguration(configurations)
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseStartup<Startup>()
        .Build()
        .Run();
}

This will take care of passing server.urls argument to Kestrel.

Deploying with Dockerfile

This is the most simple and suggested by Heroku (later on this) method to deploy. All you really need is a Dockerfile and the place to build the image. Yes, you will need to build the image by yourself (locally, in Docker hub or with CI tool) and then push it to Heroku’s registry. They don’t build images.

I tried multiple files with different base images and they all worked flawlessly. You can use Microsoft’s images (e.g. dotnet or aspnet) or build custom one where you install runtime or SDK by yourself.

I built a small demo just to demonstrate how easy it is. The source code located here, the image is here and app running at aspnet-core-dockerfile.herokuapp.com.

To deploy it (assuming the app in Heroku is aspnet-core-dockerfile):

heroku plugins:install heroku-container-registry
heroku container:login
docker pull jenyay/aspnet-core
docker tag jenyay/aspnet-core registry.heroku.com/aspnet-core-dockerfile/web
docker push registry.heroku.com/aspnet-core-dockerfile/web

BTW, there is also support for Docker Compose.

Deploying with buildpack

Heroku themself were experimenting with running ASP.NET on Mono (!). This repository has 5 years history with steady commits until one year ago. Half a year ago noliar sent PR which switches from Mono runtime to .NET Core. After nothing happened with this PR, I figured out that main contributors are no longer at Heroku, so I wrote to Heroku’s support where they basically told me that I should forget about this buildpack and go with Dockerfile.

You can use Noliar’s fork and it will work just fine. I had to fork his fork because I wanted to get ride of NodeJS installation (my application is pure API, so there is no NPM or Bower packages) and I needed to support multiple deployable projects (web and worker) within single solution.

So, to deploy with buildpack you will need to:

• Figure out which buildpack to use or create your own.

• Define buildpack in Heroku application. This can be done either via UI by pointing to one of git repositories or from CLI

  heroku buildpacks:set https://github.com/jenyayel/dotnet-buildpack

• Add .deployment file in root of your source code repository. This file instructs buildpack which project/s needs to be published. Assuming you are deploying WebAPI project, then the content of the file should be:

  [config] project = src/WebAPI

• The last piece is a Procfile which instructs Heroku how to start executables. This one also resides in root of repository and should have something similar to:

  web: cd $HOME/heroku_output/WebAPI && dotnet ./WebAPI.dll –server.urls http://+:$PORT ${CORE_ENVIRONMENT}

Final note

I still decided to stick with buildpack mainly because it just takes more time to build Docker image and push into Heroku registry, than pushing source and building using buildpack.

It worth mentioning that Container Registry and Runtime is still in Beta phase and things may change/improve over time.

Update

Dec 10 2016 : friism who was one the main contributors to original .net build pack, created an a new builpack and submitted PR. Although I didn’t test it yet, it looks much cleaner.

May 2017 : I updated buildpack to support both - csproj and project.json projects, compilation to use relevant SDK versions.

October 2017 The buildback was updated to support .NET Core 2.0

For Mac OS and Linux there are instruction on how to daemonize (autostart) the platform. So, here are the missing for Windows.

There numerous way to run a Python script as Windows Service, including the accepted answer on StackOverflow, but IMHO a much simpler approach is by using NSSM.

1. Download and extract NSSM from here

2. Run from command line \win64\nssm.exe install HomeAssistant which will launch configuration UI for service

3. In this example I installed “Home Assistant” under Python Virtual Environment located at C:\hass-env\, which places executable at C:\hass-env\Scripts\hass.exe. The configuration folder is located in %appdata%\.homeassistant\, hence will pass it location via argument -c:
   
   

4. Details screen is self explanatory:
   
   

5. I’m running it with Local System account (this is why I needed to specify configuration folder in step #3 to my %appdata%):
   
   

6. To catch log information written to console I defined I/O redirection to custom log file:
   
   

7. You can define file rotation in case output file growths fast as following:
   
   

8. Click Install service and you be able to find it in SCM:
   
   

At this stage you should be now able to start, stop and restart the service. If error thrown during startup, the service won’t start and you can check the log file for details.