<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Eugene Muthui on Medium]]></title>
        <description><![CDATA[Stories by Eugene Muthui on Medium]]></description>
        <link>https://medium.com/@EugeneJoe?source=rss-c7837f916d50------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*5yZnXKCtjq1DJwQ8</url>
            <title>Stories by Eugene Muthui on Medium</title>
            <link>https://medium.com/@EugeneJoe?source=rss-c7837f916d50------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 11:53:05 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@EugeneJoe/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Building an HR Policy Agent People Can Trust]]></title>
            <link>https://medium.com/@EugeneJoe/building-an-hr-policy-agent-people-can-trust-1238f1185023?source=rss-c7837f916d50------2</link>
            <guid isPermaLink="false">https://medium.com/p/1238f1185023</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[agentic-ai-architecture]]></category>
            <category><![CDATA[build-ai-agents]]></category>
            <dc:creator><![CDATA[Eugene Muthui]]></dc:creator>
            <pubDate>Fri, 16 Oct 2026 11:46:17 GMT</pubDate>
            <atom:updated>2026-10-16T11:46:17.401Z</atom:updated>
            <content:encoded><![CDATA[<p>Oct 16, 2026 · Eugene Muthui</p><p><em>No framework, a cheaper embedding model, and guardrails the model can’t argue with</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*W3EDBXzB-2UX-3kj" /><figcaption>Photo by <a href="https://unsplash.com/@markuswinkler?utm_source=medium&amp;utm_medium=referral">Markus Winkler</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>Most questions employees bring to HR aren’t hard, but they are tangled. The answer is usually spread across several policies, each written for its own purpose, and even with all of them open, what they mean for you depends on your own circumstances: your contract, your tenure, your timing.</p><p>Take asking whether you can work from another country for a few weeks. One policy decides whether remote work is allowed at all, another covers the tax and location review it triggers, and a third covers security while you’re abroad. Whether the answer is yes still depends on whether you’re past probation and how much notice you’re giving. So the question goes to HR, and someone works through the same documents by hand, as they do for every question like it.</p><p>An assistant could do that first pass: find the policies that apply, check them against the employee’s own record, and quote the clauses behind the answer. But HR can only hand that work over if they can trust it. Every rule it states has to come from the actual policy text, and it must never approve or change anything on its own. That’s what we set out to build.</p><h3>What we built</h3><p>Over eleven days we built HR Compass, an HR assistant that answers policy questions with citations and walks employees through two workflows: requesting PTO and asking to work from another country. Along the way we planned on LangGraph, built hybrid search and ran on Gemini embeddings. The version we shipped uses none of them.</p><p><a href="https://www.linkedin.com/in/ludenyo-wangia/">Ludenyo Wangia</a> and I built it for the Quantic AI Engineering Techniques and Architectures project.</p><p>The setup, briefly:</p><ul><li>Corpus: 13 synthetic HR policies (about 21,500 words) in Markdown, plain text, HTML and PDF, split into 121 chunks.</li><li>Agent: Claude Haiku 4.5 through OpenRouter, at temperature 0 with a fixed seed.</li><li>Tools: 12 typed tools served by a separate MCP server over Streamable HTTP. Employee lookups, PTO balances, compliance checks, policy search, email drafts and mock HR tickets.</li><li>Storage: Postgres with pgvector (Neon’s free plan) for both the policy vectors and the mock HR data.</li><li>Hosting: one Docker container on Render’s free tier, with 512 MB of memory.</li></ul><p>Every person, policy and balance is fictional. The rest of this post covers how we got there: why we skipped agent frameworks, how experiments picked our retrieval strategy and embedding model, and how we built and tuned the guardrails.</p><h3>Why we didn’t use LangChain or LangGraph</h3><p>The agent is a hand-written function-calling loop of about 65 lines, and every decision that matters for safety sits next to it as plain Python. We never adopted a framework, though our first proposal named one.</p><h3>How we got here</h3><p>The original plan was LangGraph for orchestration, with FastEmbed and FAISS for retrieval. The first build shipped neither. It used a typed state machine with keyword routing, which was predictable and fast (about 11 ms per turn) but brittle. One bug sums it up: the substring router read “laptop” as “PTO”. It also couldn’t handle open-ended questions or combine tools flexibly.</p><p>So we rebuilt it around an LLM that picks its own tools. At that point we asked the question again: now that the model is choosing, do we want a framework around it? We decided no.</p><h3>Why not</h3><ul><li>The loop is small. Call the model with the tool list, run each tool it asks for, append the results, repeat. It stops when the model calls a respond function, or after 6 tool rounds, 8 LLM calls or 90 seconds.</li><li>The important parts aren’t in the loop. What matters is what happens around each tool call: binding the acting employee, holding writes for confirmation, attaching evidence, checking citations. A framework would put an abstraction layer around exactly the code we most needed to read, test and show in the trace.</li><li>MCP already gives us the tool layer. The model’s tool schemas come straight from the MCP server’s tools/list. Tool metadata marks which arguments the host fills in, such as the employee ID, and the client strips those before the model sees them. That&#39;s the job a framework&#39;s tool abstraction would do.</li><li>Swapping models is already cheap. OpenRouter speaks the OpenAI-compatible API, so changing the model is one environment variable.</li><li>Testing is simple. The tests use a scripted fake LLM that returns predetermined tool calls, against a real MCP server and Postgres. No framework internals to mock.</li></ul><p>The core of it looks like this (simplified):</p><pre>for _ in range(max_llm_calls):<br>    must_respond = tool_rounds &gt;= max_tool_rounds<br>    response = await llm.complete(messages, tools, &quot;respond&quot; if must_respond else &quot;auto&quot;)<br>    for call in response.tool_calls:<br>        if call.name == &quot;respond&quot;:<br>            correction = await review_reply(call)  # guardrails get one say here<br>            if correction is None:<br>                return call.arguments<br>            messages.append(tool_message(call, correction))<br>            continue<br>        result = await execute(call)  # identity binding, write proposals, evidence<br>        messages.append(tool_message(call, result))<br>    tool_rounds += 1</pre><h3>What it cost us</h3><p>Skipping a framework meant writing things one would have given us. We wrote our own conversation memory (a 3,000-token window plus tool digests), server-sent event streaming and retry handling. We also hit a concurrency bug: our MCP client opened and closed its connection from different async tasks, which the SDK’s task groups don’t allow, so we had to give the connection one owner task. Even so, I’d make the same choice for an agent this size. Every line that touches safety is ours to read.</p><h3>Retrieval: vector, hybrid or keyword, and how many passages</h3><p>We shipped plain vector search returning the top 5 passages. We started with hybrid search, and we expected it to win. It didn’t.</p><h3>Building a test set first</h3><p>Before comparing anything, we wrote a gold set of 70 questions, each labelled with the policy sections that answer it:</p><ul><li>45 natural-language questions, such as “Can I work from my hometown in the same country for two weeks?”</li><li>14 questions that name a policy ID or section number, such as “What does POL-GRV-001 say?”</li><li>11 out-of-scope questions the corpus can’t answer.</li></ul><p>A script (make eval-retrieval) scores every combination of retriever and chunking against it, with no LLM involved. It runs in about a minute, so we could try an idea and know whether it helped before lunch. We compared five retrievers (keyword only, plus vector-only and hybrid for each of two embedding models) across five chunking strategies: 25 configurations.</p><h3>Hybrid lost to vector-only</h3><p>The rebuild started with hybrid search: vector and Postgres full-text results (that is, keyword search) merged with Reciprocal Rank Fusion. Across all ten vector-versus-hybrid comparisons (two models, five chunkings), hybrid never put the right section first more often than vector-only. It tied once and lost nine times.</p><p>Reciprocal Rank Fusion is a simple way to merge two ranked lists. It ignores the raw scores, which aren’t comparable between vector and keyword search, and uses only positions. A chunk earns 1 / (60 + its rank) from each list it appears in, and the two amounts are added, so a chunk ranked third in both lists (2/63) beats one ranked first in only one (1/61).</p><p>Two things went wrong:</p><ul><li>Fusion rewards the middle. Reciprocal Rank Fusion lifts a chunk that does moderately well in both lists above a chunk that is clearly best in one.</li><li>Keyword matches on common words pull in the wrong sections. For the hometown question, keyword search ranked the part-time PTO section first. Fusion pushed the correct domestic-arrangements section down to second.</li></ul><p>Keyword search on its own was the weakest option by far. It put the right section first for 56% of questions, against 80% to 100% for the vector retrievers.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Z5pRJkfV7IZOIi5v03MTbw.png" /></figure><p>Hybrid search never beat vector-only on first-place accuracy</p><p>Adding keyword results cost the most on questions that name a policy or section, where Gemini fell from 100% to 64%.</p><h3>Neither method could handle identifiers</h3><p>The 14 identifier questions exposed a blind spot in both approaches:</p><ul><li>A policy’s own ID sits in its metadata, so in the indexed text it only appears in <em>other</em> policies’ cross-references. POL-GRV-001 appears in 13 chunks, none of them in the grievance policy.</li><li>Postgres full-text search splits POL-GRV-001 into pol, grv and 001. Keyword search put the named policy first for 0 of 14 identifier questions.</li><li>Embeddings guessed policy IDs from their abbreviations reasonably well, but section numbers barely registered. Every “section N” query missed its section.</li></ul><p>The fix wasn’t a better ranker. It was skipping ranking. A policy ID in the query now restricts the search to that policy, and “section N” pins that section first. With Gemini embeddings, all 14 identifier questions then found the right section first.</p><h3>Chunking mattered more than the retriever</h3><p>One finding from the grid surprised me more than hybrid’s loss. Fixed-size windows that ignore headings were the worst setting for every retriever. With bge-small, they put the right section first for 31% of questions, against 80% for heading-aware windows. Policies are cited by section, so a chunk should never combine text from two sections. A fixed-size window cuts wherever its token count runs out, so it often ends one section and starts the next. We split by section and cut sections longer than 350 tokens into overlapping windows, which gives 121 chunks.</p><p>We picked 350 tokens before the ablation, for two reasons. The policies were written with self-contained sections of 100 to 350 words, so most sections fit in one chunk (only 11 of 110 needed splitting). And five passages of at most 350 tokens keep each search to about 1,750 tokens of prompt.</p><p>Both models index the same 121 chunks, so the evidence IDs match whichever one answers. But the size was confirmed while Gemini was the primary, and there 350-token windows and whole sections both put the right section first every time.</p><p>With bge-small, two other settings did slightly better on first place: whole sections (87%) and 256-token windows (82%), against 80% for 350. Top-5 recall was the same. We kept 350 because it caps every chunk’s length whatever later edits do to a section, and the top 5 already include the right section 97.8% of the time.</p><h3>Top 5 or top 8?</h3><p>Top-k retrieval means the search returns only the k passages that score as most similar to the question, and those passages are all the model gets to read. A larger k makes it more likely that the answer is somewhere in the results. It also costs more prompt space, and gives the model more irrelevant text to read past.</p><p>We settled on 5 passages, because the sixth, seventh and eighth bought almost nothing. On the 45 natural-language questions, with bge-small:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AuwvmlVZfX7U6--bQavLlw.png" /></figure><p>“Right section included” (hit@k) is the share of questions where at least one answering section appears among the k passages. Some questions need several sections, so “answering sections found” (recall@k) is the share of all the needed sections that appear, averaged over questions. nDCG (normalised discounted cumulative gain) is a standard score for ranking quality. It gives credit for each answering section found, shrinks that credit the lower the section is ranked, then divides by the best possible score so the result runs from 0 to 1. So a section found at rank 1 counts more than one found at rank 5, and 1.0 means the answering sections took the top places.</p><p>Going from 5 to 8 found no new questions’ answers and added 1.1 points of section recall. It also meant 60% more passage text in every prompt, on every search. The agent can still ask for up to 10 passages, or fetch a whole section, when one search isn’t enough.</p><h3>Bugs in the measuring stick</h3><p>Two of our metrics were wrong, and both flattered the wrong option:</p><ul><li>nDCG above 1. Two chunks from the same section could both earn credit. A section now scores only at its first position.</li><li>A weak proxy for multi-policy questions. We first checked that these questions reached at least two policies. Hybrid passed by adding the <em>wrong</em> second policy. The test now checks recall of the actual gold sections.</li></ul><h3>Embeddings: Gemini ranked better, and we shipped bge-small anyway</h3><p>Gemini’s embedding model beat the small local model on every retrieval measure we had. We still made the local model, bge-small-en-v1.5, the primary, and kept Gemini as the backup. Rank quality turned out to be one consideration among several, and on a free tier it wasn&#39;t the deciding one.</p><h3>Three models in a week</h3><ol><li>Hashed embeddings. The first build used signed-hash 384-dimension vectors stored in a JSON file. They were deterministic and needed no model download, but they understand nothing: paraphrase a question and the match falls apart.</li><li>Gemini (gemini-embedding-2, 768 dimensions). The rebuild switched to Gemini, using its separate text prefixes for documents and queries.</li><li>bge-small (384 dimensions, run locally through fastembed). We first brought it in to replace the hashed vectors in tests and CI, so the test suite would need no API key. Then it became the backup. Then the primary.</li></ol><h3>Head to head</h3><p>Same corpus, same chunking (section windows of 350 tokens), same 70-question gold set:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Clkj2lf8OGisIoiKbav2Pw.png" /></figure><p>The last row needs explaining. Each model needs its own cut-off for deciding that the corpus doesn’t cover a question. Gemini’s scores separate the two groups cleanly: the weakest in-scope question scored 0.729 and the strongest out-of-scope one 0.698. bge-small’s ranges overlap a little (0.647 against 0.697), so no threshold is perfect. 0.655 gives a balanced accuracy of 0.94. Below the threshold, the search tool returns evidence_sufficient=false and the prompt tells the model to say the documents don&#39;t cover the question.</p><h3>What the free tier taught us</h3><p>Gemini’s free tier shaped more of the design than its quality did:</p><ul><li>Every text in a batch counts as a request. That’s 100 a minute and 1,000 a day. Re-indexing costs 121 requests, and each comparison run 60 to 70. We used up a day’s quota in one afternoon of experiments.</li><li>The daily-limit error lies about when to retry. A daily-quota 429 still carries a short retry delay (19 seconds), but the quota only resets at midnight Pacific. Obeying it just hammers a closed door. We now recognise the daily quota from the error’s quota ID and never retry it.</li><li>Quotas belong to the Google Cloud project, not the key. A second key in the same project shares the limit. Evaluation runs now use a key from a separate project, and the comparison script refuses to call Gemini without it.</li><li>Every search is a network call. We gave query embeddings an 8-second deadline, below the 15-second tool timeout, so a hung request fails over before the tool call dies.</li></ul><p>We added a circuit breaker that sent searches to a local bge-small index of the same chunks whenever Gemini failed, and a Postgres cache of query embeddings so a repeated question cost nothing for the rest of the day. We tested it live with the daily quota exhausted: a PTO question was answered from the backup index with the right citations.</p><h3>Flipping the roles</h3><p>Once the backup worked, the obvious question was why it wasn’t the primary. The worry was memory: Render’s free tier gives 512 MB. So we measured it on the deployed service. With the model loaded and real conversations running, the container used about 400 to 405 MiB of non-reclaimable memory, which left about 20% headroom.</p><p>That settled it. We made bge-small the primary and Gemini the backup. Normal operation now spends no quota and has no network call on the search path. Since 97.8% of questions get the right section somewhere in the top 5, and the LLM reads all 5, the ranking gap matters less in practice than the first row of the table suggests. The final agent evaluation, run with bge-small, passed 29 of 30 cases with 100% citation recall.</p><p>To keep a memory spike from killing the container, a guard unloads the model above 90% of the memory limit, and reloads it only once it fits under 85% again. Unloading was harder than it sounds. Dropping the model and running Python’s garbage collector returned only 22 MiB. Also asking glibc to hand freed pages back to the operating system (malloc_trim) took memory from 164 MiB with the model loaded back down to 57 MiB.</p><p>Each model keeps its own index of the same chunks, so the evidence IDs the agent cites are identical whichever model answers. If both fail, Postgres keyword search is the last resort.</p><h3>Guardrails: take away the levers, then check the words</h3><p>Our main guardrail principle was to remove capabilities in code rather than ask the model to behave. The prompt still matters, but nothing safety-critical depends on the model following it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9IZhFtMWVxuEQ-SZuCzMoA.png" /></figure><p>Code checks every tool call and every reply the model makes</p><p>Tool calls pass the host’s checks before they reach the MCP server, and a reply passes review and finalisation before the employee sees it.</p><h3>Layer 1: take away the levers</h3><p>A prompt injection, or a confused model, can only do damage through the tools. So we took the dangerous levers out of the model’s hands:</p><ul><li>It can’t choose whose data it reads. Personal tools take the employee ID from the session, never from the model. The ID argument is hidden from the model’s tool schema. If the model supplies a different ID anyway, the host overwrites it and logs a guardrail row in the trace.</li><li>It can’t write anything. A call to a write tool becomes a proposal. The employee sees a Confirm card. Confirming signs an HMAC token bound to the action ID, the employee, the tool, a digest of the payload and a 10-minute expiry. The MCP server verifies that token before writing, and each write is idempotent.</li><li>It can’t forge a confirmation. The arguments that carry the token are marked internal in the tool metadata, so they’re stripped before the model ever sees the schema.</li></ul><p>None of this relies on the prompt. In the final evaluation, all 90 runs passed the action-safety check: no write was ever applied without a confirmation.</p><h3>Layer 2: validate what the model claims</h3><p>The model finishes by calling a structured respond function. Its cited policy facts are kept separate from its suggestions, and each fact must name the evidence it rests on. Code then checks every fact. It drops any fact that cites evidence not retrieved in this turn, or that states a number missing from its cited passage. Citations are built only from the facts that survive.</p><p>A few behaviours are forced regardless of what the model decides. If a compliance check says a request needs specialist review, or falls in a blackout period, the reply is escalated. Messages describing harassment, discrimination or retaliation are escalated too.</p><h3>Layer 3: one correction turn</h3><p>Some problems can’t be fixed by deleting a field. For these, code holds the reply back and gives the model one chance to correct it:</p><ul><li>Uncited policies. The answer names a policy (by ID or full title) that none of its facts cite. The model must search and cite it, or remove it.</li><li>Labelling a reported concern. On a sensitive report, the reply classifies what the employee described (“this constitutes discrimination”). The model must instead name the policy that covers the concern and leave the assessment to People Relations.</li><li>Wrong weekdays. The reply pairs a date with the wrong day of the week.</li></ul><p>Each check gets at most one correction per turn. If the corrected reply still has wrong weekdays or labelling sentences, code removes them before delivery.</p><h3>How evaluation tuned them</h3><p>We tuned the guardrails against a live evaluation. It started at 25 cases and grew to 30, each run three times against the real model at temperature 0. Our first live run passed 22 of 25. The final run passed 29 of 30. Most of the useful lessons came from the failures in between:</p><ul><li>Sometimes the test was wrong, not the agent. In the first run, several cases expected a plain answer where the agent escalated. A 50-day stay abroad and PTO in a blackout period both need specialist review, so the agent was right. We fixed the expectations, not the agent.</li><li>The model works out dates badly. In a live test, the agent called 21 October 2026 a Monday. It’s a Wednesday. In another, it worked out a travel checklist deadline of 27 November when the right date was 26 October. The fix had two halves: the weekday check above, and compliance tools that return the actual dates (the earliest eligible start and end, the checklist deadline). The model now repeats dates rather than computing them.</li><li>The first version of a check is usually too strict. The uncited-policy check fired on a cross-border remote work question. After the correction, the model cited a remote-work passage that itself named the Work Location and Tax Review Policy. The check still flagged that policy as uncited. We changed it so that, after the correction, a policy that a cited passage names counts as supported.</li><li>Over-triggering is a real failure mode. The conduct-label check fired on “What does the conduct policy say about retaliation?”, which is a policy question with no conduct described. It now runs only when the message reports something personal. Similarly, “What does the security policy say about phishing threats?” shouldn’t be escalated. We split the escalation keywords into always-sensitive terms and context terms such as “threat” or “unsafe”. Context terms only count next to a personal cue (“I”, “my”, “a colleague keeps…”).</li><li>The conduct-label check earned its place. In the final run it fired on the first draft of every run of our harassment-report case, which said the jokes would “constitute discrimination”. Every corrected reply instead named the grievance policy and said People Relations would assess it.</li></ul><h3>What automated scoring missed</h3><p>A person reads the recorded answers for the refusal cases, the harassment report and the PTO confirmation. That caught something no rule flagged. Asked for a colleague’s salary records, the agent refused and disclosed nothing. It passed every automated check. But it then suggested asking a manager or People Operations “for a legitimate business reason”. A refusal that points to a route to someone else’s data isn’t really a refusal. We changed the prompt so refusals of another person’s information never suggest a person, team or process to get it.</p><h3>The failure we kept</h3><p>One case still fails: “What does the conduct policy say about retaliation?” The answer is right and correctly escalated. But in its corrected reply, the model cited an evidence ID that doesn’t exist, POL-GRV-001#non-retaliation:0 (the real one is POL-GRV-001#grievance-non-retaliation:0). The citation check removed it, and our groundedness metric counts any removal as a failure. We could have loosened the metric, but we left it. The model invented an ID, the guardrail caught it, and nothing ungrounded reached the user. That seems like the right thing for the scorecard to show.</p><h3>What I’d tell myself on day one</h3><ol><li>Build the measuring stick first, then check the stick. The 70-question gold set and the evaluation runner drove every decision in this post. But twice the measurement itself was wrong: nDCG above 1, and a multi-policy test that hybrid passed by citing the wrong policy. Both errors flattered the option we turned out not to want.</li><li>Remove capabilities in code. Use the prompt for tone. The guardrails we trust are the ones the model can’t argue with: hidden ID arguments, writes held for confirmation, facts dropped when their evidence is missing.</li><li>Let tools compute and the model repeat. Every date bug we found came from the model doing arithmetic. Once the compliance tools returned the actual dates, the bugs went away.</li><li>Treat free tiers as a design constraint. Gemini’s per-project quota and Render’s 512 MB shaped the architecture more than any benchmark did.</li><li>Measure on the real deployment. bge-small used about 100 MiB more on Render than in our local rehearsal. Unloading the model only worked once we called malloc_trim. We wouldn&#39;t have known either without measuring.</li><li>Docs drift faster than code. After the rebuild, several documents still described the first build: 8 tools instead of 12, hashed embeddings, a deterministic state machine. Code changes had tests; the docs had nothing equivalent, so they fell behind until an audit caught them.</li><li>Read the answers yourself. The salary-route refusal passed every automated check. Only a person reading it noticed what was wrong.</li></ol><h3>What’s next</h3><ul><li>Re-tune chunk size for bge-small. We chose 350-token windows while Gemini was primary. With bge-small, whole sections put the right section first more often (87% against 80%).</li><li>Give the uncited-policy correction the exact evidence IDs already retrieved, which should fix the one failing case.</li><li>Check figures in the free-text answer, not just in the structured facts.</li><li>Add real sign-in. Identity binding stops the <em>model</em> from reaching another employee’s data, but in this demo anyone can pick any employee from the selector.</li><li>Move off the free tiers:</li><li>A paid Gemini tier has no daily cap, so Gemini, which ranked the right section first every time, could go back to being the primary. bge-small would stay as a local backup for outages.</li><li>A larger instance would make the memory guard unnecessary.</li><li>An always-on plan would replace the scheduled ping that keeps the free service from sleeping. Render’s free tier spins a service down after 15 minutes without traffic, and the next request then waits about a minute while the container starts. We pointed an UptimeRobot monitor at the /health endpoint every 14 minutes so it never goes idle, which uses about 744 of the 750 free instance hours a month.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1238f1185023" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Peri Planner App Dev experience]]></title>
            <link>https://medium.com/@EugeneJoe/the-peri-planner-app-dev-experience-7aac98ce40c4?source=rss-c7837f916d50------2</link>
            <guid isPermaLink="false">https://medium.com/p/7aac98ce40c4</guid>
            <category><![CDATA[flask]]></category>
            <category><![CDATA[portfolio]]></category>
            <category><![CDATA[alx-blog]]></category>
            <category><![CDATA[software-development]]></category>
            <dc:creator><![CDATA[Eugene Muthui]]></dc:creator>
            <pubDate>Thu, 11 Nov 2021 15:49:46 GMT</pubDate>
            <atom:updated>2021-11-18T08:54:31.549Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="Peri Planner Logo" src="https://cdn-images-1.medium.com/max/500/1*ue7tOsDIZrjXikTCWnglSA.jpeg" /></figure><h4>Introduction</h4><p>The Peri Planner App is a lesson planner app for peripatetic tutors in Nairobi. See, a lot of instrumental tutors and coaches in Nairobi teach in various schools and also have a handful of private students in their studios. They have to keep tabs of all their students’ progress and schedules. This quickly becomes challenging due to the dynamic nature of the job. The Peri Planner App aims to plug this tool gap by enabling tutors to create and update lesson logs for their lessons as well as keep track of their schedules. You can check it out here.</p><p>As a peripatetic tutor myself, I know the need for a quick way to update lesson logs in a manner that will be readily presentable at the end of the term in report form. A lot of tutors abhor having to write up a different report at the end of the term or having to transfer content from their physical planners to a digital format. I felt that a planning app that was tailored to our needs was sorely needed and I hope to keep working on it to adapt it to the changing needs of peripatetic tutors.</p><h4>Web App Structure</h4><figure><img alt="A data flow model diagram for the Peri Planner Web app" src="https://cdn-images-1.medium.com/max/1024/1*FeFnoeheB3PDXFbzWqkbEg.jpeg" /></figure><p>The Peri Planner App is web app accessible through your computer’s browser. The core of the app is built using python’s Flask micro-framework. I opted to use flask because I was already familiar with it and it offered a lot of the features I would need. I integrated the app with a MySQL database using a popular python library, sqlalchemy. Sqlalchemy is a fantastic library that abstracts much of the workings of the database and lets you relate your objects to database tables. On the front-end side, I relied heavily on Bootstrap 4 for styling my HTML pages. This allowed me to create responsive, stylish web pages. Some of the features I implemented include:</p><ul><li>User Login and Signup.</li><li>Student Management: view all your current students and add new students.</li><li>Lesson logs management: Add new and update existing lesson logs.</li><li>View your schedule based on slotted-in lessons.</li></ul><p>Working on my project has been a journey of tenacity. There were a lot of long nights spent figuring out various problems as they arose. One particular problem I encountered was an internal server error when I was deploying the web site. Accessing some of the pages would result in an internal error whilst others were accessible. I opened up the developer tools on my browser and opened the network tab to see the requests that were being sent while trying to access these pages. The proper requests were being sent to the server but the server couldn’t make sense of the requests. The flask app had been set up behind a web server gateway interface (gunicorn) and nginx. I realized that I had set up a prefix in my nginx configuration file that the flask app couldn’t make sense of. After a lot research, the solution lied in using the environment variable ‘SCRIPT_NAME’ when setting up the gunicorn app server and using the url_for() function instead of typing in urls in my jinja templates. Gunicorn removes the prefix before passing the request to flask as a route.</p><h4>Main takeaways</h4><figure><img alt="Learning setup" src="https://cdn-images-1.medium.com/max/1024/0*K2inemshFg2UKnXs" /><figcaption>Photo by <a href="https://unsplash.com/@tjerwin?utm_source=medium&amp;utm_medium=referral">Trent Erwin</a> on <a href="https://unsplash.com/?utm_source=medium&amp;utm_medium=referral">Unsplash</a></figcaption></figure><p>My main takeaway from this project has been the importance of detailed planning during the design phase. Capturing as much detail about the inner workings of the project will make the development stage smoother and less stressful. This project also exposed my knowledge gap in front-end technologies. I only learnt of the bootstrap framework a few days to my project presentation and later realized that using a framework such as React or Vue would have my served my needs even better. This led to the realization that I’m more comfortable with back-end roles. I’d much rather tinker with databases and app servers than buttons and divs. I intend to challenge myself to acquire basic front-end development skills to have a better understanding of the entire project development process.</p><h4>About the Author</h4><p>I am a graduate mechatronics engineer, software engineer in training, and moonlight trumpeter based in Nairobi. I have a very strong affinity to automation and figuring out how technology can offer more convenience in our lives.</p><ul><li><a href="https://www.linkedin.com/in/eugene-joe-muthui-954b633a">LinkedIn Profile</a>.</li><li><a href="https://github.com/EugeneJoe/Peri_Planner">Peri Planner GitHub Repository</a>.</li><li><a href="https://eugenejoe.github.io/">Peri Planner App Landing page</a>.</li><li><a href="http://periplanner.joebnb.tech/login">Peri Planner Website</a>.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7aac98ce40c4" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[What happens when you type holbertonschool.com in your browser and press Enter]]></title>
            <link>https://medium.com/@EugeneJoe/what-happens-when-you-type-holbertonschool-com-in-your-browser-and-press-enter-230a24ab3f75?source=rss-c7837f916d50------2</link>
            <guid isPermaLink="false">https://medium.com/p/230a24ab3f75</guid>
            <category><![CDATA[tcp-ip]]></category>
            <category><![CDATA[https]]></category>
            <category><![CDATA[servers]]></category>
            <category><![CDATA[ip]]></category>
            <category><![CDATA[website]]></category>
            <dc:creator><![CDATA[Eugene Muthui]]></dc:creator>
            <pubDate>Sun, 05 Sep 2021 17:54:04 GMT</pubDate>
            <atom:updated>2021-09-05T17:54:04.757Z</atom:updated>
            <content:encoded><![CDATA[<p>Imagine that you’re on your computer and you want to visit the Facebook website. Imagine having to type ‘31.13.67.35’ every time you wanted to visit this site. It’s a bit harder to remember but I can do it, you tell yourself. Now imagine having to remember a bunch of random numbers for every website you’d like to visit. This gets very challenging, very quickly.</p><p>This is the reason why the <a href="https://www.networkworld.com/article/3268449/what-is-dns-and-how-does-it-work.html">DNS</a> (Domain Name System) exists. At its most basic, DNS is a directory of names that match with numbers. The numbers, in this case, are IP addresses, which computers use to communicate with each other. It translates the domain name of a website a.k.a the website name you type in in your browser e.g Facebook.com or twitter.com into the website’s IP address. Every machine on the Internet has a unique number assigned to it, called an IP address. Without a unique IP address for your machine, you will not be able to communicate with other devices, users, and computers on the Internet. Think of an <a href="https://www.bleepingcomputer.com/tutorials/ip-addresses-explained/">IP</a> address as if it were a telephone number, each one being unique and used to identify a way to reach you and only you or as the postal address of the computer that has the files and data for the Facebook website. Without this DNS system, we would have to remember the IP addresses for all our favourite websites, a feat much harder to accomplish than recalling the website name.</p><h4>DNS Requests</h4><p>When you type ‘holbertonschool.com’ on your browser and press enter, DNS request is a request sent from the browser on your computer to the Domain Name Servers to get the IP address of the website we want to visit. The Domain Name Server will send back the IP address of the website you want to visit to your browser.</p><p>Your browser can now communicate directly with the server hosting the website you are interested in. But what is a server, you ask? Well, imagine you walk into a barbershop and want to get a haircut. The barber cuts your hair for you i.e, serves you or provides a service to you, his client. This is exactly the same relationship that exists between your browser and the server hosting your website. A server is simply a computer or piece of software running on a computer that provides a service to another computer or software or program. So your browser communicates with the server hosting the website and asks for a web page. The server then retrieves the web page from its file system and sends that back to the browser. A web page is made up of various types of files, most commonly:</p><ul><li>A HTML (Hyper Text Markup Language) file containing all the text that’s displayed on your browser.</li><li>A CSS (Cascading Style Sheets) file containing all the styling properties that are responsible for how the text is formatted and how it appears. This includes any layout properties, colour scheme of the website, font size, colour and type etc.</li><li>A JavaScript file, which is responsible for the interactive functionality of the website.</li></ul><p>Once your browser receives the web page, it renders it on your screen and you are able to interact with the website.</p><h4>How communication between the client and the server happens</h4><p>But how does your browser communicate with the web server? Well this happens through the <a href="https://searchnetworking.techtarget.com/definition/TCP-IP">TCP/IP</a> protocol. TCP/IP stands for Transmission Control Protocol/Internet Protocol and it is a suite of communication protocols used to interconnect computers and other network devices on the internet or in a private network. TCP and IP are the two main protocols in the suite, though others are included in the suite. TCP defines how applications can create channels of communication across a network. To enhance efficiency, data sent through TCP/IP is broken up into smaller segments called data packets. These data packets are all aware of the destination address and thus can take the fastest route to the destination. Sometimes this means different packets will take different routes to get to the destination. IP defines how to address and route each packet to make sure it reaches the right destination and ensures that every packet is received at the destination address. If one fails to reach the destination, it is sent again, thus ensuring zero data loss during transmission.</p><p>The TCP/IP protocol consists of <a href="https://www.freecodecamp.org/news/what-is-tcp-ip-layers-and-protocols-explained/">various layers</a> each dealing with a different aspect of data transmission, as described below.</p><h4>Application Layer</h4><p>Different applications on your computer require internet connectivity i.e, your browser, your zoom application, that game you’re playing online etc. The application layer manages sharing the computer’s network resources across all these applications. The widely known<a href="https://www.lifewire.com/hypertext-transfer-protocol-817944"> HTTP</a> and HTTPS protocols operate on this level. HTTP (Hyper Text Transfer Protocol) is a transmission protocol for sending documents between web servers and their clients. HTTPS (Hyper Text Transfer Protocol Secure) is a secure version of HTTP where the data sent between client and server is encrypted to ensure no one else can read it.</p><p>This encryption is made possible by the use of a pair of encryption keys, a public key and a private key. A private key is kept safely on a website server and should not be shared while a public key is shared with anyone requesting access to the website. <a href="https://www.ssl.com/faqs/faq-what-is-ssl/">SSL</a> (Secure Socket Layer) is the standard technology for keeping an internet connection secure when using HTTPS. Each website has a certificate that is signed with its public key. When a client requests access to a website, the server sends back a response, including its certificate that bears its public key. The client then encrypts a message using that public key and sends it to the server. This message can only be decrypted using the private key corresponding to that public key. Once the server receives the encrypted message, it decrypts it and sends back a response. The client can then verify this response and if satisfied,a secure session can then be set up between the server and the client. The use of public and private keys can be very resource-intensive and can slow down communication.</p><p>Thus, once a secure connection has been established, a single, shared key is generated which is used for further encryption and communication between the server and the client. This entire process is known as an <a href="https://www.ssl.com/article/ssl-tls-handshake-overview/">SSL Handshake</a> and this is just a basic summary of the entire process which is a lot more complicated. Thankfully, this process happens in the background and the user is never aware of it. However, most browsers will display highly visual cues to alert the user when they are using a secure connection. These cues involve:</p><ol><li>A closed padlock on the left of your address bar. This padlock could be green depending on the type of browser used and the type of certificate installed by a website.</li><li>The address of the website may start with “https://” instead of “http://” to indicate that a secure connection is being used.</li></ol><h4>Transport Layer</h4><p>This layer is responsible for ensuring reliability in data transfer. The TCP protocol operates here. TCP splits the data from the application layer into smaller packets of data, numbers them and adds more addressing information. When the data packets are sent, it performs error-checking by having the recipient send a response back to ensure the data packet was received. If TCP doesn’t get the right response back, it re-sends that data packet, thus ensuring no data loss.</p><h4>Internet Layer</h4><p>This layer is responsible for the addressing system of computers on the internet and describes how data is sent and received over the internet. All devices connected on the internet have an address known as an IP address. There are two types of <a href="https://www.webopedia.com/insights/ipv6-ipv4-difference/">IP</a> addresses. IPv4 addresses contain a maximum of 32 bits separated into four segments by a period e.g <strong>31.13.67.35</strong>. IPv6 addresses contain a maximum of 128 bits written in hexadecimal format and separated by colons e.g <strong>3ffe:1900:4545:3:200:f8ff:fe21:67cf</strong>. IPv6 was developed due to a concern that we would run out of addresses on the old IPv4 system.</p><p>The internet layer is responsible for determining which route a data packet will take to get to its destination. It provides no guarantee that the packets will be received in the right order or even take the same path.</p><h4>Physical/Link Layer</h4><p>This layer represents the physical medium used to transmit your data and is dependent on the hardware used by your computer or device. It is also responsible for converting your data into a format that can be transmitted via the transmission medium such as light packets for the fiber optic medium, or electrical signals for a cable medium. It also converts the data back into readable format on the receiving end.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kYYV1ebzOtr5BSf3sr6Pag.png" /><figcaption>From browser to server and back to browser</figcaption></figure><h3>Server-Side Technology</h3><h4>Load Balancers</h4><p>As a website’s popularity grows, demand for access to the website grows as well. At some point, the number of requests sent to a server exceeds what it can handle efficiently and the website can become slow to access or even unavailable. Thus, most popular websites will have two or more servers that handle requests from clients. However, these servers still need to be accessible from one website name or IP address, otherwise a website could have multiple names, which would be very confusing. This is made possible by the use of a load balancer. A load balancer is a server that handles the distribution of incoming requests a.k.a the load, to the different servers that have been set up to serve that website. When a DNS request is made, it returns the IP address of the load balancer, the load balancer receives all the requests made to that IP address and distributes them, thus ensuring that the website remains reliable and efficient. It also ensures that a website always remains available since if one server becomes temporarily unavailable, the load balancer can send requests to the remaining servers, adding a level of redundancy.</p><p>The load balancer is also set up with a firewall to protect it from malicious users on the internet. The firewall could detect suspicious patterns in incoming traffic that could indicate a website is being attacked and prevent such an attack, or it could filter the incoming requests to block any users who have been barred from accessing the website. Still on security, in the case where HTTPS is used, the load balancer could also handle decrypting the incoming traffic and transmitting the data to the other servers through unencrypted HTTP. It is also responsible for encrypting outgoing traffic.</p><p>Once a request reaches the server’s side, it can be serviced in a number of different ways depending on what the request entails. Recall the definition of a server; a server is simply a computer or piece of software running on a computer that provides a service to another computer or software or program. On the server-side, different servers could be set up to provide different services in order to fully service a request. In most website configurations you may find the following set up:</p><h4>Web server</h4><p>This is software that listens for incoming HTTP requests and serves up any form of static data i.e. data that already exists in shareable format and does not need to be updated in any way. This is the primary method through which you interact with a website when you make a request to a website.</p><h4>Application Server</h4><p>This is software that provides some form of functionality in a website. This functionality, also known as business logic, could be unique to that website. A good example is when you use a PDF converter website to convert your documents to PDF format. An application server would provide the functionality of converting your document to PDF format. This distinguishes it completely from, for example, a website that offers photo editing services.</p><h4>Database Server</h4><p>A database server handles requests to create, update, retrieve or destroy data from a database. A layer of abstraction from database access is required to ensure that malicious users are unable to either corrupt the data or gain access to protected data. A good example is when you create a post on Facebook. This translates into a request to a database server to create a data record. When you like a post, this could translate into a data record in a database being updated with a new number of likes.</p><p>Thus, once a request is fully serviced by any one of these servers, it communicates with the web server, which then sends back the updated files to for the web page that will be displayed.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=230a24ab3f75" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>