michasdev · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026
diff --git a/README.md b/README.md
@@ -2,102 +2,85 @@
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="apps/desktop/src/renderer/src/assets/logos/mildstack-logo-full-white.png">
     <source media="(prefers-color-scheme: light)" srcset="apps/desktop/src/renderer/src/assets/logos/mildstack-logo-full-black.png">
-    <img alt="MildStack Logo" src="apps/desktop/src/renderer/src/assets/logos/mildstack-logo-full-black.png" width="400">
+    <img alt="MildStack Logo" src="apps/desktop/src/renderer/src/assets/logos/mildstack-logo-full-black.png" width="450">
   </picture>
 </p>
 
-# MildStack
-
-> A lightweight, local-first AWS emulator built for developers. The best localstack alternative.
-
-MildStack is an open-source project that helps you run and test AWS-like services locally with a focus on speed, simplicity, and low resource usage.
-
-It is designed to be a practical alternative for local cloud development, without unnecessary overhead.
-
-## Why MildStack?
-
-Working with AWS-based applications locally can be slow, heavy, or fragmented.
-
-MildStack aims to make that experience better by being:
-
-- lightweight
-- fast
-- developer-friendly
-- open-source
-- easy to extend
-- suitable for local development workflows
-
-## What it is
+<p align="center">
+  <strong>The Lightweight, Drop-in Replacement for LocalStack.</strong><br />
+  Fast, Open Source, and Developer-First.
+</p>
 
-MildStack is being built as a small ecosystem around a core emulator.
+<p align="center">
+  <a href="https://mildstack.dev">Website</a> •
+  <a href="#key-features">Key Features</a> •
+  <a href="#supported-services">Supported Services</a> •
+  <a href="https://discord.gg/your-invite">Community</a>
+</p>
 
-The project currently includes:
+---
 
-- a Go-based core for the emulator and API
-- a CLI for local control and startup
-- a desktop app for a more visual experience and resource browsing
-- a web presence for documentation and project info
+## ⚡️ What is MildStack?
 
-## Project goals
+MildStack is a high-performance, local-first AWS emulator designed to streamline your cloud development workflow. Unlike heavy alternatives that require Docker and significant system resources, MildStack is built in **Go** for maximum efficiency and speed.
 
-MildStack is intended to be:
+Stop waiting for containers to spin up. Start building instantly with a local cloud that feels "mild" on your CPU but "spicy" on productivity.
 
-- a local AWS-like emulator
-- simple to run and use
-- performant and memory-efficient
-- modular by design
-- consistent across services
-- easy to evolve over time
+## ✨ Why MildStack?
 
-## Tech stack
+- **🚀 Instant-On**: No Docker required. MildStack runs as a native binary, starting in milliseconds.
+- **🖥️ Desktop App**: A beautiful, intuitive UI to browse S3 buckets, query DynamoDB tables, and monitor SQS queues without leaving your IDE.
+- **🍃 Ultra-Lightweight**: Minimal RAM and CPU footprint. Keep your machine cool while simulating complex cloud architectures.
+- **🔌 Drop-in Compatibility**: Works seamlessly with official AWS SDKs and CLI. Just change your endpoint URL.
+- **📡 Offline-First**: Build and test your cloud applications on a plane, a train, or anywhere without an internet connection.
+- **💰 100% Free**: No "Pro" tiers for basic features. Everything you need for local development, open-source and free.
 
-The project is centered around:
+## 🛠 Supported Services
 
-- **Go** for the core runtime, API, and CLI
-- **Gin** for the HTTP API
-- **Charm** for the terminal UI and CLI experience
-- **Electron** for the desktop app
-- **React** for the website and docs
+MildStack is rapidly evolving. We currently provide robust support for core AWS services:
 
-## Design principles
+| Service | Status | Features |
+| :--- | :--- | :--- |
+| **S3** | ✅ Active | Bucket management, Multipart uploads, Metadata support |
+| **DynamoDB** | ✅ Active | Tables, GSI/LSI support, Rich querying & filtering |
+| **SQS** | ✅ Active | Message queues, DLQ redrive, FIFO support |
+| **SNS** |  📅 Planned | Topic publishing, basic subscriptions |
+| **Lambda** | 📅 Planned | Local execution of serverless functions |
+| **EventBridge** | 📅 Planned | Event-driven architecture simulation |
 
-The core of the project follows:
+## 📦 The Ecosystem
 
-- **Domain-Driven Design**
-- **Clean Architecture**
-- **SOLID principles**
+MildStack isn't just an emulator; it's a complete development environment:
 
-The goal is to keep the emulator core independent from frameworks and easy to maintain as new services are added.
+### 1. The Core Engine
+Written in Go, our core provides a high-concurrency, low-latency API that mimics AWS service behavior with precision.
 
-## Philosophy
+### 2. The MildStack CLI
+A modern, terminal-based control center (powered by Charm/BubbleTea) to manage your local instances, view logs, and monitor service health.
 
-MildStack is built around a few simple ideas:
+### 3. The Desktop Browser
+An Electron-powered visual console that gives you a "Production-like" experience for inspecting your local resources. Browse objects, edit items, and peek at messages with ease.
 
-- local-first
-- developer-first
-- performance-oriented
-- minimal overhead
-- clear architecture
-- open-source friendly
+---
 
-## Current status
+## 🗺 Roadmap
 
-MildStack is still in early development.
+Our goal is to cover the 80% of AWS services used in 95% of applications. Check our [Roadmap](https://mildstack.dev/roadmap) to see what's coming next, including Lambda support, IAM simulation, and more.
 
-This README is intentionally lightweight and provisional until the project has proper installation docs, usage guides, and service-specific documentation.
+## 🤝 Contributing
 
-## Contributing
+We love contributors! Whether you're fixing a bug, adding a new service, or improving the documentation, your help is welcome.
 
-Contributions are welcome.
+1. Check out our [Contribution Guidelines](CONTRIBUTING.md).
+2. Join our [Discord community](https://discord.gg/your-invite) to discuss ideas.
+3. Spread the word! 🌟
 
-If you want to help, you can:
+## 📄 License
 
-- suggest services to emulate first
-- review architecture decisions
-- improve documentation
-- test the project locally
-- help build core features
+MildStack is released under the **MIT License**. Build freely.
 
-## License
+---
 
-MIT.
+<p align="center">
+  Built with ❤️ for developers by <a href="https://github.com/michasdev">Michel</a> and the community.
+</p>
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
@@ -1,153 +1,56 @@
-# MildStack App
+# 🖥️ MildStack Desktop
 
-MildStack App is an open source desktop app for browsing and inspecting resources from MildStack, a localstack-like local AWS environment.
+**The Visual Console for your Local Cloud.**
 
-The project is currently in its foundation stage. It starts from an electron-vite Electron,
-React, and TypeScript application and is being shaped into a local developer console for
-MildStack workflows.
+MildStack Desktop is a cross-platform companion app for [MildStack](https://github.com/michasdev/mildstack). It provides an intuitive, production-grade interface to manage, browse, and inspect your local AWS-compatible resources without touching the command line.
 
-## What it is
+<p align="center">
+  <img src="../../apps/desktop/resources/screenshot-placeholder.png" alt="MildStack Desktop Interface" width="100%">
+</p>
 
-MildStack App gives developers a desktop UI for local MildStack resources so they do not
-need to reach for raw command-line checks for every inspection task.
+## ✨ Features
 
-The version 1 target is local MildStack resource browsing. For version 1, real AWS account
-management is not supported for the version 1 local MildStack browsing scope.
+- **📂 S3 Explorer**: Browse buckets, navigate prefixes (folders), upload objects, and inspect metadata with a modern file-manager experience.
+- **📊 DynamoDB Browser**: Query tables using a rich UI, filter items, edit attributes, and visualize your data structures instantly.
+- **📩 SQS Monitor**: Peek at messages, monitor queue depths, and manage Dead Letter Queues (DLQ) with ease.
+- **🛠 Instance Management**: Start, stop, and switch between multiple MildStack runtime instances directly from the UI.
 
-## Scope
+## 🏗 Built for Developers
 
-Current scope:
+MildStack Desktop is built with a modern stack optimized for performance and safety:
 
-- Cross-platform Electron desktop app using React and TypeScript.
-- Contributor documentation, local setup, and build scripts from the existing project.
-- A strict Electron boundary where privileged MildStack communication belongs outside the
-  renderer.
+- **Electron & Vite**: Fast startup and smooth transitions.
+- **React & TypeScript**: Robust, type-safe UI components.
+- **IPC Safety**: Privileged communication with the MildStack core is handled outside the renderer process for maximum security.
+- **Clean Architecture**: Decoupled features that allow for rapid extension to new AWS services.
 
-Deferred roadmap work, not current setup:
+## 🗺 Roadmap
 
-- Tailwind CSS renderer styling.
-- CossUI setup through the planned shadcn CLI path.
-- Multipage desktop navigation.
-- Typed MildStack IPC from renderer to preload to main.
-- Generic MildStack resource browsing.
-- Dedicated S3 explorer.
-- Dedicated DynamoDB explorer.
+We are continuously adding new capabilities to the desktop experience:
 
-No current local setup step depends on these deferred items.
+- [x] S3 Bucket & Object Browsing
+- [x] DynamoDB Table & Item Exploration
+- [x] SQS Message Peeking
+- [ ] Lambda Log Stream Monitoring
+- [ ] IAM Policy Visualizer
+- [ ] CloudFormation Stack Viewer
 
-## How it works
+---
 
-The app is split across the standard Electron process boundaries:
+## 🤝 Contributing
 
-- `src/main/` owns the Electron main process, native window lifecycle, privileged IPC handlers,
-  and future MildStack command coordination.
-- `src/preload/` owns the safe bridge exposed to the renderer.
-- `src/renderer/src/` owns the React and TypeScript UI that runs in the renderer process.
+We welcome contributions to the desktop app! Whether it's improving the UI, adding new service browsers, or fixing bugs.
 
-Renderer code must not import Electron directly or call shell APIs directly. MildStack
-communication will be implemented behind Electron main/preload APIs in a later phase, then
-exposed to React through a typed renderer-safe contract.
+1. Fork the repository.
+2. Check the [Local Setup Guide](https://github.com/michasdev/mildstack/blob/main/apps/desktop/CONTRIBUTING.md) (coming soon).
+3. Submit a PR!
 
-## Local setup
+## 📄 License
 
-Install dependencies:
+MIT. Part of the MildStack ecosystem.
 
-```bash
-npm install
-```
+---
 
-Start the local Electron development app:
-
-```bash
-npm run dev
-```
-
-Preview the built Electron app:
-
-```bash
-npm run start
-```
-
-## Available scripts
-
-The current `package.json` scripts are:
-
-- `npm run format` - Format the repository with Prettier.
-- `npm run lint` - Run ESLint.
-- `npm run typecheck:node` - Typecheck Electron main, preload, and build config code.
-- `npm run typecheck:web` - Typecheck the React renderer and preload type declarations.
-- `npm run typecheck` - Run node and web typechecks.
-- `npm run start` - Preview the Electron app with electron-vite.
-- `npm run dev` - Start the Electron development app.
-- `npm run build` - Typecheck and build with electron-vite.
-- `npm run postinstall` - Install Electron Builder app dependencies.
-- `npm run build:unpack` - Build and produce an unpacked Electron Builder output.
-- `npm run build:win` - Build a Windows package.
-- `npm run build:mac` - Build a macOS package.
-- `npm run build:linux` - Build Linux packages.
-
-## Project structure
-
-```text
-src/
-  main/              Electron main process
-  preload/           Renderer-safe preload bridge
-  renderer/
-    index.html       Renderer HTML shell
-    src/             React renderer source
-resources/           Desktop app resources
-build/               Packaging support files
-```
-
-Configuration lives in:
-
-- `electron.vite.config.ts` - Electron Vite main, preload, and renderer build config.
-- `tsconfig.node.json` - TypeScript config for Electron-side code.
-- `tsconfig.web.json` - TypeScript config for renderer-side code.
-- `electron-builder.yml` - Cross-platform packaging config.
-
-## Roadmap
-
-Version 1 is planned as a sequence of foundation and browsing work:
-
-1. Project and renderer foundation: README, renderer structure, and renderer aliases.
-2. Tailwind and CossUI setup: planned styling and component foundation.
-3. Desktop app shell and navigation: planned multipage app shell.
-4. Typed MildStack Electron API: planned renderer to preload to main communication.
-5. Generic resource browser: planned local MildStack service and resource inspection.
-6. S3 explorer: planned dedicated bucket, prefix, object, and metadata browsing.
-7. DynamoDB explorer: planned dedicated table, metadata, and item browsing.
-
-These roadmap items describe planned work, not current completed functionality.
-
-## Contributing
-
-MildStack App is intended to be public open source software. Contributions should preserve
-the desktop Electron target, keep renderer code browser-safe, and document only behavior that
-exists in the current codebase unless it is clearly marked as planned roadmap work.
-
-Use the current npm scripts for validation before submitting changes:
-
-```bash
-npm run typecheck
-npm run lint
-```
-
-## S3 smoke test
-
-The app now includes a smoke runner for the MildStack S3 surface:
-
-```bash
-npm run s3:smoke
-```
-
-By default it targets the local MildStack runtime API at
-`http://127.0.0.1:4566/api/v1/runtime/services/s3`. Override that with
-`MILDSTACK_API_BASE_URL` if your server is running elsewhere.
-
-An optional `--native` mode is also available for S3-compatible endpoints via
-`@aws-sdk/client-s3`:
-
-```bash
-npm run s3:smoke -- --native
-```
+<p align="center">
+  Stop guessing. Start seeing. 🚀
+</p>
diff --git a/apps/desktop/scripts/dynamo-smoke.cjs b/apps/desktop/scripts/dynamo-smoke.cjs
@@ -42,7 +42,7 @@ main().catch((error) => {
 });
 
 async function main() {
-  const endpoint = process.env.MILDSTACK_DYNAMODB_ENDPOINT || process.env.AWS_DYNAMODB_ENDPOINT || `http://localhost:${port}`;
+  const endpoint = process.env.MILDSTACK_DYNAMODB_ENDPOINT || `http://localhost:${port}`;
 
   console.log(`Running AWS SDK smoke mode against ${endpoint}`);
   const client = new DynamoDBClient({

diff --git a/apps/desktop/scripts/s3-smoke.cjs b/apps/desktop/scripts/s3-smoke.cjs
@@ -43,7 +43,7 @@ function expectDefined(actual, message) {
 }
 
 async function main() {
-  const endpoint = process.env.MILDSTACK_S3_ENDPOINT || process.env.AWS_S3_ENDPOINT || `http://localhost:${port}`;
+  const endpoint = process.env.MILDSTACK_S3_ENDPOINT || `http://localhost:${port}`;
 
   console.log(`Running S3 behavioral validation against ${endpoint}`);
   const client = new S3Client({

diff --git a/apps/desktop/scripts/sqs-smoke.cjs b/apps/desktop/scripts/sqs-smoke.cjs
@@ -45,7 +45,7 @@ main().catch((error) => {
 });
 
 async function main() {
-  const endpoint = process.env.MILDSTACK_SQS_ENDPOINT || process.env.AWS_SQS_ENDPOINT || `http://localhost:${port}`;
+  const endpoint = process.env.MILDSTACK_SQS_ENDPOINT || `http://localhost:${port}`;
 
   console.log(`Running AWS SDK smoke mode against ${endpoint}`);
   const client = new SQSClient({

diff --git a/apps/desktop/src/main/dynamodb-ipc.ts b/apps/desktop/src/main/dynamodb-ipc.ts
@@ -1,4 +1,4 @@
-import { getActiveInstancePort } from './instance-state'
+import { resolveLocalEndpoint } from './local-endpoint'
 import { registerValidatedHandler } from './ipc-middleware'
 import {
   DynamoDBClient,
@@ -269,8 +269,7 @@ function getClient(region = 'us-east-1'): DynamoDBClient {
 }
 
 function resolveDynamoDBEndpoint(): string {
-  const port = getActiveInstancePort()
-  return process.env.MILDSTACK_DYNAMODB_ENDPOINT || process.env.AWS_DYNAMODB_ENDPOINT || `http://127.0.0.1:${port}`
+  return resolveLocalEndpoint('dynamodb')
 }
 
 function normalizeRegion(region?: string): string {