DEV Community: Panic Engineer

RepoDeck: Automating the One README I Keep Forgetting to Update

Panic Engineer — Sat, 08 Aug 2026 16:30:43 +0000

I build a lot of projects.

Some are web applications, some are developer tools, some are experiments, and lately I've also been exploring things like browser games and YouTube Playables.

There is one small problem that keeps appearing after every project:

My GitHub Profile README becomes outdated.

The project exists. The repository exists. The code is there.

But my profile still has an old list of projects.

Updating it manually isn't difficult. That's actually what makes the problem interesting.

It's just repetitive enough that I eventually forget to do it.

So I built RepoDeck.

RepoDeck on GitHub

The Problem

The workflow usually looks something like this:

Build a project.
Push it to GitHub.
Maybe deploy it somewhere.
Eventually remember that the project should also appear on your profile.
Open the profile README.
Manually add/update the project.
Repeat.

The actual coding isn't the problem.

The problem is keeping two representations of the same project synchronized:

Project Repository
       │
       │  manually remember
       ▼
GitHub Profile README

And the more projects you have, the more annoying this becomes.

What About Existing README Tools?

There are already tools and generators that can help create GitHub profile READMEs.

But while looking at the problem from my own perspective, I wasn't looking for another README generator.

I didn't want to maintain a separate portfolio dataset.

I didn't want to manually enter every project into another configuration file.

And I didn't want the profile README to become the source of truth for my projects.

The repositories already contain the information.

So I decided to reverse the relationship:

The project repository should be the source of truth. The profile README should be the generated view.

That became the core idea behind RepoDeck.

The RepoDeck Workflow

Instead of manually editing the profile README, each participating repository contains a small metadata file:

.github/project.md

RepoDeck periodically discovers repositories containing that file, validates their metadata, generates the project showcase, and synchronizes it into the profile README.

The resulting workflow is:

Project Repository
       │
       ▼
.github/project.md
       │
       ▼
RepoDeck
       │
       ├── Discover
       ├── Parse
       ├── Validate
       ├── Render
       └── Inject
       │
       ▼
GitHub Profile README

The important part is that the profile README is no longer manually maintained for the generated section.

The Architecture

I deliberately kept RepoDeck small and separated the responsibilities instead of putting everything into one script.

The current structure looks like:

src/
├── index.ts
├── config.ts
├── github/
│   ├── githubClient.ts
│   ├── githubContent.ts
│   └── githubDiscovery.ts
├── markdown/
│   ├── injector.ts
│   ├── parser.ts
│   ├── renderer.ts
│   └── schema.ts
├── services/
│   ├── profileReadme.ts
│   ├── projectDiscovery.ts
│   ├── projectLoader.ts
│   └── readmeUpdater.ts
└── utils/
    ├── fileReader.ts
    └── remoteLoader.ts

This isn't because having more folders automatically makes code better.

It is because the responsibilities are genuinely different.

1. Discovery

RepoDeck first asks GitHub for the authenticated user's repositories.

It doesn't have a hardcoded list of projects.

Instead, repositories opt into RepoDeck by containing:

.github/project.md

That means adding a new project doesn't require modifying RepoDeck itself.

Just add the metadata file to the repository.

2. Metadata as the Contract

The metadata file uses YAML frontmatter.

For example:

---
title: RepoDeck
description: An automated CI/CD pipeline for keeping a GitHub Profile README synchronized with project repositories.
category: Automation
status: Active
featured: true
tech:
  - TypeScript
  - Node.js
  - Octokit
  - Zod
  - GitHub Actions
repo: https://github.com/kaushik0010/repodeck
---

The important design decision here is that the schema only contains information useful for the profile presentation.

For example:

title
description
category
status
featured
tech
repository URL
live URL

I intentionally didn't try to put everything about a project into this file.

It's portfolio metadata, not another README.

3. Runtime Validation

The metadata comes from repositories outside the core application.

That means I don't trust it blindly.

RepoDeck uses Zod to validate the parsed metadata against a strict schema.

Conceptually:

GitHub
  │
  ▼
project.md
  │
  ▼
YAML Frontmatter
  │
  ▼
Zod Validation
  │
  ├── Valid → Continue
  │
  └── Invalid → Fail

This was one of the things I wanted to learn properly while building the project:

TypeScript types alone don't protect you from malformed external data.

The TypeScript type describes what my application expects.

Zod validates what actually arrived.

4. Rendering

Once the metadata has been validated, RepoDeck turns it into Markdown.

I initially used a Markdown table.

Then I changed my mind.

Tables looked structured, but they became increasingly awkward once I considered:

mobile GitHub clients
descriptions of different lengths
projects with or without links
games without repositories
projects with only a live URL
future categories

So I switched to a showcase-style layout:

### ⭐ RepoDeck

An automated GitHub Profile README synchronization tool.

- 🏷️ Category: Automation
- 🛠 Tech: TypeScript · Node.js · Octokit
- 🔗 GitHub Repository

This is also why I separated the renderer from the rest of the pipeline.

The data acquisition layer doesn't care how the project is displayed.

If I ever wanted a different presentation format, I could replace the renderer without rewriting GitHub discovery.

5. Injection With Explicit Boundaries

RepoDeck doesn't rewrite the entire profile README.

That would be dangerous.

Instead, I added explicit boundaries:

<!-- REPODECK:START -->

<!-- REPODECK:END -->

RepoDeck only owns the content between these markers.

Everything outside them belongs to the user.

The injector also validates that:

both markers exist
neither marker is duplicated
the markers are in the correct order

This gives RepoDeck a clearly defined write boundary.

Profile README

┌───────────────────────────────┐
│ Personal introduction         │
│ Skills                        │
│ Other sections                │
│                               │
│ <!-- REPODECK:START -->       │
│                               │
│   RepoDeck generated content  │
│                               │
│ <!-- REPODECK:END -->         │
│                               │
│ Contact information           │
└───────────────────────────────┘

That separation was important to me.

Automation should know exactly what it owns.

6. Idempotency

This is probably one of my favorite parts of the project.

RepoDeck doesn't create a GitHub commit every time it runs.

Before updating the README, it compares:

current README
        vs
generated README

If they're identical:

No changes detected

and the process stops.

If they're different, only then does RepoDeck update the file.

This gives us:

Same input → same output → no unnecessary commit.

That matters because the workflow runs automatically every day.

Without change detection, an automation that runs daily could create a lot of useless Git history.

7. GitHub SHA and Optimistic Concurrency

While implementing the update step, I also learned about something I hadn't previously thought much about: GitHub's file SHA.

When RepoDeck fetches the profile README, GitHub gives us the current file SHA.

When updating the file, RepoDeck sends that SHA back.

Conceptually:

RepoDeck reads README
       │
       ▼
README + SHA
       │
       │
       ├── Nobody changed it
       │        ↓
       │     Update
       │
       └── Someone changed it
                ↓
             Conflict

This prevents RepoDeck from blindly overwriting a newer version of the README.

It's a small detail, but it introduced me to the idea of optimistic concurrency control in a practical situation.

8. Configuration

I also didn't want application-wide policies scattered throughout the codebase.

So RepoDeck has a deliberately tiny configuration module:

PROJECT_METADATA_PATH
INCLUDE_PRIVATE
INCLUDE_ARCHIVED
COMMIT_MESSAGE

That's it.

I intentionally avoided turning config.ts into a dumping ground for every constant in the application.

For example, the README injection markers remain inside the injector because they're part of the injector's responsibility.

This was another useful architectural lesson:

Not every constant belongs in a global configuration file.

9. GitHub Actions

Once the local pipeline worked, I wanted RepoDeck to actually solve the original problem.

So I moved the execution into GitHub Actions.

The workflow runs daily and can also be triggered manually.

The production pipeline is roughly:

GitHub Actions
      │
      ├── Checkout
      ├── Setup Node 22
      ├── npm ci
      ├── Typecheck
      ├── Build
      └── Run RepoDeck
                │
                ▼
          GitHub API
                │
                ▼
       Profile README

I also added:

concurrency protection
a five-minute job timeout
deterministic npm ci
TypeScript type checking
a production build
least-privilege permissions for the workflow runner

Authentication Was Another Learning Experience

One of the questions I initially had was:

Why not just use GitHub's built-in GITHUB_TOKEN?

Because RepoDeck isn't only modifying the repository where the workflow runs.

It needs to:

discover my repositories
read project metadata from them
read my profile README
update my profile README

The built-in Actions token wasn't the right identity for this architecture.

So for my current personal setup, RepoDeck uses a fine-grained Personal Access Token stored as a GitHub Actions repository secret.

The important distinction is:

GitHub Secret
     │
     ▼
REPODECK_PAT
     │
     ▼
Workflow environment
     │
     ▼
GITHUB_TOKEN
     │
     ▼
Octokit

The actual token never lives in the repository source code.

And because this is an open-source repository, that separation is essential.

What I Learned Building It

The interesting part of RepoDeck wasn't really the final feature.

It was everything I had to understand to make a relatively small automation reliable.

Some of the things I learned while building it:

1. Separate data acquisition from presentation

GitHub discovery shouldn't know how the README looks.

The renderer shouldn't know where projects came from.

That separation made changing the table into a showcase layout almost trivial.

2. External data needs runtime validation

TypeScript can't validate data coming from GitHub.

Zod can.

3. Automation needs idempotency

If a scheduled process produces the same result, it shouldn't create another commit.

4. Write boundaries matter

Automation should never assume it owns an entire document when it only needs one section.

5. Concurrency isn't only a distributed-systems problem

The GitHub SHA mechanism made optimistic concurrency something I could see and implement in a very concrete way.

6. CI catches things local development can hide

One of the first workflow runs failed because TypeScript's strict checks caught an unused API response.

Another failure came from my own project metadata missing a required title.

Those failures were useful.

They proved the CI pipeline was actually doing its job.

Why I Kept RepoDeck Small

There was a temptation to keep adding features.

Multiple renderers.

More metadata fields.

Custom templates.

A plugin system.

A GitHub App.

A marketplace action.

But I stopped.

The current version already solves the problem I originally wanted to solve:

Keep my GitHub Profile README's project section synchronized with my actual repositories without manually maintaining two sources of truth.

I don't want to invent a roadmap just to make the project look bigger.

If I eventually discover a real problem worth solving, I'll build it then.

The Result

Today the workflow is simple:

Build a project
      ↓
Add/update .github/project.md
      ↓
Push
      ↓
RepoDeck discovers it
      ↓
RepoDeck validates the metadata
      ↓
RepoDeck generates the showcase
      ↓
RepoDeck updates the profile README
      ↓
Done

And because the process is scheduled, I don't have to remember to update my profile after every project.

That's exactly what I wanted.

Not a huge platform.

Not a SaaS product.

Just a small piece of automation that removes a repetitive task from my own development workflow.

Open Source

RepoDeck is open source, and I'd genuinely love to see how other developers would approach the same problem.

If you maintain a GitHub profile with multiple projects, I'd especially be interested in hearing how you currently keep your project showcase updated.

Repository: github.com/kaushik0010/repodeck

If you find the idea useful, a ⭐ or fork is always appreciated.

And if you see an architectural decision you'd approach differently, I'd be even more interested in that.

Final Thought

The project started with a very small annoyance:

"I keep forgetting to update my GitHub README."

It ended up teaching me about runtime validation, separation of concerns, idempotency, optimistic concurrency, GitHub APIs, authentication, secrets, CI/CD, scheduled automation, and designing systems around explicit ownership boundaries.

That's probably my favorite kind of project:

one that solves a small real problem while forcing me to learn something substantially bigger.

What Building and Deploying a Real Production App Taught Me Beyond Tutorials

Panic Engineer — Mon, 18 May 2026 09:39:53 +0000

Recently I finished building and deploying a production real-estate platform for a non-technical client using:

Next.js
MongoDB
Cloudinary
Vercel

The project itself wasn’t “massive” from an enterprise perspective, but it taught me something important:

real-world software engineering starts where tutorials usually stop.

A lot of my learning during this project had very little to do with writing React components or building CRUD APIs.

Instead, most of the valuable lessons came from:

debugging production issues
handling infrastructure constraints
deployment behavior
SEO/discoverability
UX/business tradeoffs
understanding how technical decisions affect real users

The Difference Between “Building Features” and “Shipping Products”

Before this project, most of my learning came from:

tutorials
isolated side projects
local development environments

In those environments:

APIs usually work
deployment is ignored
infra is abstracted away
assets are small
performance doesn’t matter much
search engines don’t exist
users don’t exist

Production projects behave very differently.

Once real users, real hosting platforms and real business requirements enter the picture, software engineering becomes much more holistic.

Vercel Payload Limits and Large Image Uploads

One of the first interesting issues I encountered happened during property creation.

The admin could upload multiple high-quality property images. Initially everything worked fine with smaller images, but once I started testing realistic production scenarios with larger files, uploads suddenly started failing.

At first I suspected:

Cloudinary upload issues
MongoDB problems
request handling bugs

None of those were actually the problem.

The real issue was that the total request payload exceeded Vercel’s limits before the upload logic even completed.

This was one of those moments where I realized:
production platforms have infrastructure constraints you rarely encounter in tutorials.

The Fix

Instead of blindly increasing limits or changing infrastructure immediately, I implemented client-side image optimization/compression before submission.

The result:

drastically reduced payload size
significantly improved reliability
better upload performance
reduced bandwidth usage

This was also a reminder that optimization is often about understanding constraints rather than prematurely overengineering systems.

Cloudinary PDF Preview Behavior

Another interesting issue involved property PDFs.

The client wanted uploaded PDFs to preview directly in browser rather than forcing users/admins to download them.

Initially, Cloudinary-hosted PDFs were downloading instead of previewing.

I tried:

URL manipulation approaches
response behavior tweaks
different delivery methods

Eventually I discovered that using Google Docs Viewer as a lightweight preview layer solved the issue cleanly.

The implementation itself wasn’t complicated, but the interesting part was the debugging process:
understanding browser behavior, file delivery behavior and how external services interact together.

Deployment Is a Different Skillset Entirely

Before this project I underestimated how much engineering exists beyond writing application code.

Deployment introduced an entirely different category of problems:

DNS propagation
custom domain setup
SSL behavior
Vercel deployment restrictions
GitHub contributor behavior
infrastructure caching

One interesting moment happened during custom domain setup.

Some devices/networks showed the updated Vercel deployment immediately, while others still displayed the default GoDaddy placeholder page.

Initially it looked like a broken deployment.

The actual issue:
DNS propagation and ISP-level caching differences.

This taught me that deployment debugging often involves understanding distributed systems behavior more than application logic itself.

SEO Is More Technical Than I Expected

This was also the first time I handled SEO/discoverability setup seriously for a production project.

That included:

sitemap.xml
robots.txt
OpenGraph metadata
canonical URLs
Google Search Console
indexing requests

One thing I realized quickly:
deploying a website does not mean search engines automatically understand or discover it properly.

There’s an entire layer of infrastructure and communication happening between:

your application
crawlers
social platforms
indexing systems

Even after submitting the sitemap and requesting indexing, Google still needed time to crawl and process the website.

At first many pages simply showed:
“URL is unknown to Google.”

That experience helped me understand that SEO is less about “gaming rankings” and more about:
clarity, discoverability and technical communication.

Lighthouse Scores vs Real UX

Another useful lesson came from performance optimization.

I tested the project using Lighthouse/PageSpeed and the scores were actually quite good overall.

But I also realized something important:
blindly chasing perfect benchmark scores can become counterproductive.

For example:
real-estate platforms naturally depend heavily on high-quality imagery because trust and presentation matter.

Aggressively compressing everything or removing visual quality purely to maximize Lighthouse scores can negatively affect actual user perception.

That changed how I think about optimization.

Good engineering is often about balancing tradeoffs:

performance
aesthetics
usability
responsiveness
business requirements

rather than maximizing a single metric at all costs.

Mobile-First Thinking Changed A Lot

This project also changed how I think about mobile UX.

Real-estate traffic is heavily mobile-first.

While testing the production deployment on actual devices, I realized that many interfaces that felt “clean” on desktop became frustrating on smaller screens.

That affected decisions around:

spacing
modal behavior
tap targets
navigation
lead capture flow
scrolling experience

Responsive design is not only about making layouts fit smaller screens.
It’s about reducing friction during real interactions.

AI Tools Accelerated Development, But Didn’t Replace Engineering

AI tools definitely accelerated parts of development during this project.

They were extremely useful for:

speeding up implementation
generating boilerplate
exploring approaches
debugging directionally

But the hardest parts still required engineering judgment:

identifying root causes
understanding constraints
evaluating tradeoffs
adapting architecture
debugging infrastructure issues
balancing UX and business goals

The “generate code” layer was only one part of shipping the product.

Technical Decisions Directly Affect Business Outcomes

One of the biggest mindset shifts during this project was realizing how directly technical decisions influence business outcomes.

For example:

improving upload reliability improved admin experience
better metadata improved social previews
SEO setup improved discoverability
mobile UX decisions reduced friction
lead capture flow decisions affected conversions

The project gradually stopped feeling like:
“building features”

and started feeling more like:
“designing systems that solve business problems reliably.”

Why This Project Was Valuable

The most valuable part of this project wasn’t the final deployment itself.

It was learning that real-world engineering involves much more than writing code:

debugging unfamiliar problems
understanding infrastructure behavior
communicating with non-technical stakeholders
balancing tradeoffs
improving reliability
thinking about users/business impact
shipping systems end-to-end

I think that’s why production projects teach differently from tutorials.

They force you to move beyond:
“Does this work locally?”

and start thinking:

What happens in production?
What happens under constraints?
What happens for real users?
What happens after deployment?
What breaks unexpectedly?
How do we recover/debug systematically?

Still learning, but this project definitely changed how I think about software engineering.

Building SOC-AI: Sub-Second Security Triage with Groq & Kestra

Panic Engineer — Tue, 06 Jan 2026 12:38:00 +0000

The Motivation: Solving Alert Fatigue 🛡️

Security teams are drowning in logs. I built SOC-AI solo during the AI Agents Assemble Hackathon (hosted on @wemakedevs) to prove that AI can handle the "boring" triage while humans keep control.

The Architecture

Triage: Groq (Llama-3.3) for 500ms log analysis.
Orchestration: Kestra for semi-autonomous remediation.
Frontend: Next.js 15 (Live on Vercel!).

Technical Deep Dive – Reliable AI & Orchestration

One of the biggest challenges in AI agents is hallucination. In a security context, a "hallucinated" IP address or action could be a disaster. I solved this using two core patterns:

1. Forcing Structured Output with Zod & Groq

I didn't just ask the AI to "analyze the log." I defined a strict contract using Zod. This ensures that the high-speed Llama-3.3 model on Groq returns a precise JSON object that my backend can trust.

// Define the Triage Schema
const SecurityTriageSchema = z.object({
  severity: z.enum(["low", "medium", "high", "critical"]),
  threat_type: z.string().describe("Categorization like Brute Force, SQLi, etc."),
  action_suggested: z.enum(["block_ip", "disable_user", "monitor"]),
  reasoning: z.string()
});

// Forcing Groq to adhere to the schema
const chatCompletion = await groq.chat.completions.create({
  model: "llama-3.3-70b-versatile",
  response_format: { type: "json_object" }, // Crucial for reliable JSON
  messages: [
    { role: "system", content: "You are a SOC Triage Agent. Output ONLY JSON." },
    { role: "user", content: `Analyze this log: ${rawLogData}` }
  ],
});

2. Semi-Autonomous Remediation via Kestra

Trust is everything in security. Instead of letting the AI run wild, I built a Human-in-the-Loop system.

When the AI suggests an action (like block_ip), it appears on my Next.js Dashboard. Only after I click "Approve" does the backend trigger a Kestra Workflow.

Why Kestra?

Retries: If the Firewall API is down, Kestra handles the retry logic.
Audit Trail: Every action taken is logged visually in the Kestra UI.
Separation of Concerns: My Next.js app handles the UI, while Kestra handles the heavy infrastructure automation.

The Result

By combining Groq's speed with Kestra's reliability, SOC-AI can triage a log and present a remediation plan to an analyst in less than a second.

This project was a solo build, and it taught me that the future of AI isn't just about the "chat" - it's about orchestration.

Links & Demo

GitHub: https://github.com/kaushik0010/soc-ai
Video Walkthrough: https://youtu.be/LbuHXiPznJE

What are your thoughts on semi-autonomous security? Would you trust an AI to suggest your firewall rules? Let's talk in the comments!