I’ve been running FastAPI in production for a payment processing platform in Mexico for the past couple of years. We handle SPEI transfers (Mexico’s interbank transfer system), OXXO Pay (cash payments at convenience stores), and crypto on-ramps through multiple PSP integrations.
I wanted to share some real lessons from production that I don’t see discussed much.
The stack

FastAPI + async SQLAlchemy 2.0 + asyncpg
PostgreSQL + Redis (rate limiting + caching)
Docker → AWS ECS Fargate
GitHub Actions CI/CD
Alembic for migrations

Lesson 1: Webhook state machines save your life
When you process payments, you receive webhooks from payment providers. The naive approach is to just update the payment status directly. Don’t do this.
We built a webhook state machine where each payment goes through defined states: pending → processing → completed/failed. Every state transition is logged with timestamps. When a payment provider sends duplicate webhooks (and they will), the state machine just ignores transitions that don’t make sense.
This saved us during a reconciliation where we found timezone boundary issues between UTC and CST that were causing mismatches at midnight.
Lesson 2: Alembic migrations + ECS = restart loops
This one hurt. We had an Alembic migration that was taking too long, and ECS health checks were killing the container before the migration finished. Container restarts, migration starts over, health check fails again. Infinite loop.
Fix: Run migrations as a separate ECS task before deploying the new container. Never run migrations on startup in production.
Lesson 3: psycopg2 + LIKE queries will bite you
If you use % in LIKE queries with psycopg2 and parameterized queries, you need %% for literal percent signs when mixed with %s placeholders. We had a bug where a search endpoint was silently returning empty results.

Wrong

cursor.execute(“SELECT * FROM users WHERE name LIKE ‘%s%'”, (search,))

Right

cursor.execute(“SELECT * FROM users WHERE name LIKE %s”, (f”%{search}%”,))
Lesson 4: VARCHAR timestamps are a trap
One of our PSP integrations stores created_at as VARCHAR instead of TIMESTAMP. Every time we need to do date comparisons, we have to CAST(created_at AS TIMESTAMP). If you’re designing your schema, always use proper TIMESTAMP columns.
Lesson 5: Rate limiting is not optional
We got hit with a brute force attack on our auth endpoints within the first month. Redis-backed rate limiting with SlowAPI saved us. 5 attempts per minute on login, 20 requests per minute on general endpoints.
Lesson 6: Connection pooling matters more than you think
Our KYC service was falling over under load. The fix? Increasing the connection pool from 10 to 50 connections. That’s it. Went from random 500 errors to zero issues.
The architecture pattern that works
After iterating through multiple services, this is the pattern I settled on:
Repository (data access)
→ Service (business logic)
→ Endpoint (HTTP layer)
Each layer only talks to the one below it. Dependencies are injected via FastAPI’s Depends(). Testing becomes trivial — just mock the repository layer.

After refining this over 10+ deployments, I packaged the boilerplate into a starter kit with the full auth system, async DB, Docker, CI/CD, and tests. It’s on my Gumroad if anyone wants it. But the lessons above are the real value — the code is just the implementation.
I also deploy production AWS infrastructure for teams that don’t want to deal with Terraform/ECS — details here if that’s useful.
Happy to answer questions about running FastAPI in production, dealing with Mexican payment providers, or anything else.

If you’ve spent more than a week in web development, you’ve encountered REST APIs. They are the glue of the modern internet, connecting front-end frameworks to back-end databases and enabling third-party integrations that we take for granted.

But there is a massive difference between “making an API call” and “understanding RESTful architecture.” Today, we’re going deep. We’ll start with the basics and move into the advanced patterns that separate junior developers from senior architects.

Want to dive deeper into full-stack patterns? Check out more resources at NeedleCode.

What Exactly is REST?

REST (Representational State Transfer) isn’t a protocol like HTTP; it’s an architectural style. Introduced by Roy Fielding in his 2000 dissertation, it was designed to make the web more scalable and flexible.

When an API is “RESTful,” it means it follows a specific set of rules that allow different systems to communicate seamlessly, regardless of the language they are written in.

The 5 Pillars of RESTful Design

To build a truly RESTful system, you must adhere to these constraints:

1. Client-Server Separation: The UI (Client) and the Data (Server) are independent. You can swap your React frontend for a mobile app without changing a single line of your backend logic.
2. Statelessness: This is the most critical constraint. The server does not store any “session” data about the client. Every single request must contain all the information (including credentials) needed to process it.
3. Cacheability: Responses must define themselves as cacheable to prevent clients from requesting the same data repeatedly, reducing latency.
4. Uniform Interface: This simplifies the architecture. Whether you are fetching a user or a product, the method of interaction (URLs, HTTP verbs) should feel consistent.
5. Layered System: A client shouldn’t know if it’s connected directly to the database server or an intermediate proxy/load balancer.

The Developer’s Toolbox: HTTP Methods

In REST, we treat everything as a Resource. We manipulate these resources using standard HTTP verbs.

Pro-Tip: A common interview question is the difference between PUT and PATCH. Remember: PUT replaces the entire object, while PATCH only modifies the specific fields you send.

Deciphering the Server: Status Codes

As a dev, you need to speak “Status Code.” They tell you exactly what happened without parsing a huge JSON body.

• 2xx (Success): 200 OK (Standard success), 201 Created (Success after POST).
• 4xx (Client Error): 400 Bad Request (Your JSON is malformed), 401 Unauthorized (You forgot the token), 404 Not Found (Endpoint doesn’t exist).
• 5xx (Server Error): 500 Internal Server Error (Your backend code crashed).

Moving to Advanced Territory

Once you’ve mastered the basics, you’ll face real-world challenges like performance and scale.

1. Pagination and Filtering

Never return SELECT * FROM users. If you have 100,000 users, your API will crash. Use query parameters:
GET /api/v1/orders?page=2&limit=50&status=shipped

2. Stateless Auth with JWT

Since REST is stateless, we don’t use server-side sessions. Instead, we use JSON Web Tokens (JWT). The client sends the token in the Authorization header with every request.

3. API Versioning

Change is inevitable. To avoid breaking your users’ apps, version your URL:
https://api.needlecode.com/v1/products
https://api.needlecode.com/v2/products

4. The “Final Boss”: HATEOAS

HATEOAS (Hypermedia as the Engine of Application State) means your API provides links to guide the client.

{
  "user_id": 123,
  "name": "Dev",
  "links": [
    { "rel": "self", "href": "/users/123" },
    { "rel": "delete", "href": "/users/123", "method": "DELETE" }
  ]
}

This makes your API self-discoverable, though it is often skipped in simpler internal projects.

Summary

REST APIs are popular because they are predictable and scalable. By mastering these constraints and methods, you aren’t just “coding an endpoint”—you’re designing a system.

What’s your biggest struggle with API design? Let’s chat in the comments!

For more deep dives into system architecture and backend development, visit us at NeedleCode.

The 404 Not Found error is the “Ghost in the Machine” of the web. We’ve all seen it, and as developers, we’ve all accidentally caused it. While it’s the most recognizable HTTP status code, handling it correctly is the difference between a professional, SEO-optimized application and a leaky bucket that loses users.

In this guide, we’re diving deep into the mechanics of the 404 error, how to troubleshoot it, and how to implement robust fixes for modern web stacks.

What is a 404 Error (Technically)?

From an HTTP/1.1 perspective, a 404 Not Found is a client-side error. It indicates that the client (the browser or crawler) could successfully communicate with the server, but the server could not map the requested URI to a specific resource.

Unlike a 500 error (Server Error) or a 403 (Forbidden), a 404 implies that the resource might be missing temporarily or has been moved permanently without a pointer.

Common Root Causes in Development

Before you start debugging, identify where the disconnect is happening:

1. Routing Logic Mismatches: In Single Page Applications (SPAs) like React or Vue, 404s often occur when the server isn’t configured to redirect all requests to index.html.
2. Case Sensitivity: On Linux-based servers (most production environments), /Assets/Logo.png and /assets/logo.png are different files. Locally on Windows or macOS, they might work fine—leading to “it works on my machine” syndrome.
3. Permissions/Ownership: If the server process doesn’t have read permissions for a file, it may return a 404 to avoid leaking information about the file’s existence (or a 403).
4. Permalinks & .htaccess: In WordPress or PHP environments, a corrupted .htaccess file often breaks the rewrite rules.

How to Fix 404 Errors: The Developer’s Toolkit

1. Server-Side Redirects (The Right Way)

If you’ve moved content, don’t let the old URL die. Use a 301 Permanent Redirect. This preserves “link juice” and SEO authority.

Apache (.htaccess):

Redirect 301 /old-feature-slug /new-feature-slug

Nginx (nginx.conf):

location /old-path {
    return 301 /new-path;
}

2. Handling 404s in Modern Frameworks

Express.js (Node.js):
Always place your 404 handler at the very bottom of your middleware stack, after all defined routes.

// Your routes here...
app.get('/api/data', (req, res) => { ... });

// The Catch-all 404
app.use((req, res, next) => {
  res.status(404).json({
    error: "Resource not found",
    message: "If you think this is a bug, please contact [email protected]"
  });
});

React Router (v6):

<Routes>
  <Route path="/" element={<Home />} />
  <Route path="/about" element={<About />} />
  {/* The 404 "No Match" Route */}
  <Route path="*" element={<NotFoundPage />} />
</Routes>

3. Automation and Monitoring

Don’t wait for users to report broken links.

• Google Search Console: Check the “Coverage” report regularly.
• Screaming Frog: Run a crawl on your staging environment before every major deployment.
• Custom Logging: Log 404 occurrences in your backend (e.g., using Winston or Morgan) to identify patterns of mistyped URLs.

The Anatomy of a High-Conversion 404 Page

A 404 doesn’t have to be a dead end. From a UX perspective, a great 404 page should:

• Maintain Branding: Don’t use the default browser white-and-gray page.
• Provide a Way Out: Include a search bar and a “Home” button.
• Inject Personality: A bit of humor goes a long way in reducing user frustration.
• Internal Links: Link to your most popular documentation or products.

Impact on SEO

Search engines don’t penalize you for having some 404s—it’s a natural part of the web’s evolution. However, a high volume of 404s from internal links signals a “low-quality” site to crawlers.

Pro-tip: If a high-authority external site links to a page on your site that no longer exists, you are losing valuable SEO equity. Always redirect those specific URLs to the next most relevant page.

Conclusion

Mastering error handling is a core skill for any full-stack developer. By moving from “passive” 404 handling to “active” routing management, you ensure a smoother experience for both users and search bots.

For more deep dives into web performance, backend optimization, and developer tools, visit us at NeedleCode. We help developers bridge the gap between “code that works” and “code that scales.”

Originally published at needlecode.com

You Shouldn’t Have to Tell the AI Who to Be

Last week I wrote about typing “act as a senior architect” 47 times per week. The friction of manually assigning roles to an AI that should be able to figure it out.

This week I want to go deeper. Not the pitch — the plumbing. How does signal-based routing actually work inside PRISM Forge? What does the routing engine look at? How does it decide?

And — because build-in-public means showing the dents — the 3 times it broke in ways I didn’t expect.

The Core Idea: Intent Detection, Not Commands

Most persona systems work like menus. Pick a role from a list. Type a command. Toggle a mode.

Signal-based routing works differently. You talk naturally. The system listens for signals in your language and assembles the right team.

“I’m stuck on this auth bug” contains two signals: stuck (creative problem-solving) and bug (debugging/validation). The routing engine reads both, decides who leads, and who supports.

No slash commands. No mode toggles. No “act as.”

Anatomy of the Routing Engine

PRISM Forge’s routing engine has four layers that fire on every single message:

Layer 1: Hard Overrides

Three things bypass all logic:

• “War room” — loads all 27 personas into active debate. Susie moderates.
• Explicit name — “Winston, how should this be architected?” Always routes to the named persona.
• Mode switch — system context changes (Plan mode, Agent mode) activate mode defaults.

These are cheap checks. If none fire, the engine moves to intent classification.

Layer 2: Intent Classification

Every message maps to one of 9 intent categories:

Here’s the critical design decision: a single message can span multiple intents. “Plan how to refactor the auth module — I think it’s too complex” spans Plan + Build + Challenge. The engine evaluates holistically, not sequentially. It doesn’t stop at the first match.

Layer 3: Signal Detection

This is where it gets interesting. The engine maintains two signal tables:

Shared signals co-activate multiple personas. When someone says “audit,” three personas are relevant: Mary (investigation), Quinn (validation), and Boris (structural conformance). The engine decides who leads based on the full message context.

Specialist signals are exclusive triggers. “First principles” activates Musk (Radical Reductionist). “Hero’s journey” activates Campbell (Mythic Storyteller). These are unambiguous.

There are 24 shared signals and 23 specialist signal groups across all 28 personas. Every persona has a documented activation path. Nothing is magic — it’s a lookup table with contextual judgment on top.

Layer 4: Team Assembly

The engine doesn’t just pick one persona. It assembles a team:

• Primary — one persona leads the response. Sets the structure, answers the core question.
• Supporting — additional personas contribute distinct perspectives. Each one must earn their seat by adding something genuinely different.

Example: you say “the auth module is too complex, let’s simplify and rebuild it.”

• Jobs (Combinatorial Genius) leads — “simplify” and “too complex” are his signals
• Amelia (Developer) supports — “rebuild” means implementation is coming
• Winston (Architect) supports — architectural implications of simplification

Three perspectives in one response. Each attributed. Each distinct. No blended consensus voice.

The Orchestrator: Susie

All four layers are orchestrated by Susie, the Chief of Staff. She’s not a persona you talk to — she’s the intelligence running behind every turn.

On Turn 1 of every session, Susie activates unconditionally. She scans your project state (git, todos, handoffs, memory) and delivers a sitrep:

• Active: what you’re working on
• Blocked: what’s stuck
• Stale: what hasn’t moved
• Recommended: who should lead this session

After Turn 1, Susie evaluates every message, re-assembles the team if needed, and only announces when the roster changes. If you send 5 messages about planning, the team stays stable. No noise.

The key insight: Susie evaluates holistically. All signals, all domain matches, all cross-workflow hooks are inputs to one team assembly decision. She doesn’t process them sequentially and stop at the first match. She considers everything and picks the best team.

The 3 Times It Broke

Here’s where build-in-public gets honest.

Break 1: Signal Collision

Early in development, I typed: “Let’s brainstorm how to simplify the architecture.”

Three strong signals fired simultaneously:

• “brainstorm” → Carson (Brainstorming Coach)
• “simplify” → Jobs (Combinatorial Genius)
• “architecture” → Winston (Architect)

All three had legitimate claims to lead. The result? A response that tried to be all three at once. Brainstorming structure with simplification opinions wrapped in architectural framing. It was a mess. No clear voice. No clear direction.

The fix: Explicit primary selection with a tiebreaker. The engine now picks ONE primary based on which signal is strongest in context. In this case, “brainstorm” as the verb (the action the user wants) beats “simplify” (the lens) and “architecture” (the domain). Carson leads. Jobs and Winston support. Clear hierarchy, clear voices.

Break 2: The Consensus Trap

I built a “war room” feature where all personas discuss a decision. Early version: everyone agreed with each other.

Jobs would say “simplify.” Victor would say “I agree with Jobs.” Winston would say “Jobs is right, and architecturally this supports his point.” Twenty-seven personas producing one opinion. Useless.

The problem was subtle. The AI’s default behavior is to be agreeable. When you load multiple personas into one context, they naturally converge because the underlying model wants to be helpful and non-contradictory.

The fix: Susie became an active moderator with an explicit mandate: surface disagreement. Her orchestration rules now include: “A war room where everyone agrees is a failed war room.” She actively draws out dissent: “Jobs, would you cut this? Victor, is this the right approach at all? Dali, what assumption are we not questioning?”

The result: war rooms now produce genuine tension. Jobs wants to cut scope. Carson says cutting is premature — we haven’t explored alternatives. Winston sides with Jobs on scope but wants Carson’s option analysis first. Real tradeoffs. Real decisions.

Break 3: Over-Routing

For a while, the engine was too eager. A simple question like “what does this function do?” would activate Mary (investigation), Winston (architecture), Quinn (validation), and Paige (documentation) — four personas to answer what should have been a one-voice response.

The engine was technically correct. The question touches investigation, architecture, validation, and documentation domains. But four voices for a simple question is noise, not depth.

The fix: Team size guidance. Every persona on the team must earn their seat. A team of 2 with genuine perspectives beats a team of 8 with filler. The engine now considers message complexity. Simple questions get one voice. Complex, multi-faceted problems get the full team. The threshold isn’t a rule — it’s judgment, guided by the principle that extra voices must add something the primary couldn’t provide alone.

What I’d Build Differently

If I started over today, three things would change:

1. Signal weights, not signal matches. The current system treats all signal matches equally and relies on contextual judgment for tiebreaking. A weighted system where “the verb matters more than the noun” would have prevented Break 1 from the start.

2. Disagreement scaffolding from day one. I bolted on active moderation after the consensus trap. It should have been foundational. Any multi-agent system that doesn’t explicitly design for disagreement will produce consensus by default. The AI wants to agree. You have to engineer the tension.

3. Graduated complexity. Simple questions should feel simple. Complex questions should feel like a team. The transition between these modes took longer to get right than the routing engine itself.

Try It Yourself

PRISM Forge is MIT licensed and free:

npx prism-forge install

28 personas. Signal-based routing. No commands to memorize.

GitHub: prism-forge/prism-forge

This is part of a 12-post series on building PRISM Forge. Last week: the problem with manual persona prompting. Next week: meet John, the product manager who asks “why are we doing this?” before anyone writes a line of code — and what happens when he clashes with Bob over planning vs simplification.

Follow along: @DrakkoTarkin on X | @drakkotarkin.bsky.social on Bluesky

Most AI apps today try to do things for you automatically.
But when it comes to personal data — like money or health — that can feel risky.
So I explored a different pattern:

What if AI suggests actions, but never executes without approval?

🧠 The Idea: Approval-Gated AI

Instead of this:

User → AI → Action happens

I built around this:

User → AI → Draft → User approves → Action happens

💬 Example

You type:

“Add coffee for 40”

The AI:

• Parses the intent
• Prepares the expense entry
• Shows it to you

You:

• ✅ Approve → saved
• ❌ Reject → nothing happens

⚖️ Why This Matters

In domains like:

• Finance
• Health / nutrition
• Personal logs

Users care about control and accuracy.

Problems with full automation

• Silent mistakes
• Wrong assumptions
• Loss of trust

Problems with manual apps

• Too slow
• Too much friction

🔄 This Pattern Sits in Between

Approval-gated AI is:

• Faster than forms
• Safer than automation

🧪 Where I Applied It

I’ve been prototyping this idea in a small app where AI helps with:

• Expense and income tracking
• Budget alerts
• Nutrition logging (calories and macros from descriptions)
• Receipt parsing

Everything goes through user approval first.

🤔 Trade-offs I Observed

✅ Pros

• Builds trust quickly
• Prevents unexpected changes
• Makes AI behavior transparent

❌ Cons

• Adds an extra step
• Can feel repetitive for simple actions

🧩 Open UX Questions

This is where I’d love input:

• Should small actions auto-approve?
• Should users be able to set confidence thresholds?
• When does confirmation become annoying instead of helpful?

🚀 Implementation Stack

• React 19
• Hono
• Cloudflare Workers + D1 (SQLite)
• Drizzle ORM
• Tailwind
• Radix UI

🔗 Demo & Project

• 🎥 Demo: https://www.youtube.com/watch?v=V09mr6b7RXU
• 🌐 App: https://keepmylog.com

💬 Final Thought

AI doesn’t always need to be autonomous.
Sometimes the best UX is:

AI that assists decisively — but lets humans stay in control.

Curious how others are thinking about this pattern.