Dev

CONTRIBUTING.md

@@ -0,0 +1,5 @@
+# Contributing
+
+Thanks for contributing! Full guidelines live in [`docs/contributing.md`](./docs/contributing.md).
+
+For AI agent conventions, see [`AGENTS.md`](./AGENTS.md).

README.md

@@ -1,39 +1,33 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Loopback
 
-## Getting Started
+A local operator dashboard for AWS services running on your machine — built for teams using [LocalStack](https://www.localstack.cloud/) or [Floci](https://github.com/floci-io/floci).
 
-First, run the development server:
+Loopback gives you a visual interface to browse, inspect, and interact with your local AWS resources without leaving the browser. No credentials, no AWS console, no context switching.
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
-
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
-
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
-
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+## Services
 
-## Learn More
+| Service | What you can do |
+|---------|----------------|
+| S3 | Browse buckets, upload/download objects |
+| SQS | View queues, send and consume messages |
+| SNS | Manage topics and subscriptions |
+| DynamoDB | Browse tables, query and edit items |
+| Lambda | List functions, invoke with custom payloads |
+| CloudWatch Logs | Stream and filter log groups |
 
-To learn more about Next.js, take a look at the following resources:
+Additional tools: SDK Request Inspector, Snapshots, Timeline, Terminal, Seed, Config.
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Quick start
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+See [Getting Started](./docs/getting-started.md) for full prerequisites and setup steps.
 
-## Deploy on Vercel
-
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+```bash
+pnpm install
+export AWS_ENDPOINT_URL=http://localhost:4566
+pnpm dev
+```
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+Open [http://localhost:3000](http://localhost:3000).
 
 ## Docker
 
@@ -118,3 +112,9 @@ Releases are cut from the `Release` workflow (Actions → **Release** → _Run w
 SemVer bump (`patch | minor | major`) and a channel (`stable | alpha | beta | rc`); the workflow
 bumps `package.json`, tags the commit, builds multi-arch, and publishes to both registries.
 
+## Documentation
+
+- [Getting Started](./docs/getting-started.md) — prerequisites, install, run, and test locally
+- [LocalStack / Floci Setup](./docs/localstack-setup.md) — local AWS emulation with Docker
+- [Architecture](./docs/architecture.md) — feature-sliced layout, RSC, i18n routing
+- [Contributing](./docs/contributing.md) — workflow, commit conventions, PR guidelines

docs/architecture.md

@@ -0,0 +1,143 @@
+# Architecture
+
+This document describes the high-level structure of the application. It covers the request flow, the feature-sliced directory layout, the AWS SDK boundary, i18n routing, and state management conventions.
+
+No implementation code is included — this is a structural reference.
+
+---
+
+## Request flow
+
+```mermaid
+flowchart LR
+    Browser["Browser\n(React Client)"]
+    AppRouter["Next.js App Router\n(Server Components\n+ Route Handlers)"]
+    SDK["AWS SDK\n(server-side only)"]
+    Emulator["LocalStack / Floci\n(local)"]
+    AWS["AWS\n(production)"]
+
+    Browser -->|RSC payload / fetch| AppRouter
+    AppRouter -->|serialized data| Browser
+    AppRouter --> SDK
+    SDK --> Emulator
+    SDK --> AWS
+```
+
+The browser never talks to AWS directly. All AWS SDK calls happen inside Server Components or Route Handlers. The browser receives serialized data (JSON, RSC payload).
+
+---
+
+## Feature-sliced structure
+
+The codebase is organized around AWS service domains. Each domain lives under `features/` and follows a consistent internal layout:
+
+```mermaid
+flowchart TD
+    Features["features/"]
+
+    Features --> S3["s3/"]
+    Features --> SQS["sqs/"]
+    Features --> DynamoDB["dynamodb/"]
+    Features --> Lambda["lambda/"]
+    Features --> SNS["sns/"]
+    Features --> Logs["logs/"]
+    Features --> Inspector["inspector/"]
+    Features --> Snapshots["snapshots/"]
+    Features --> Terminal["terminal/"]
+    Features --> Seed["seed/"]
+    Features --> Config["config/"]
+    Features --> Dashboard["dashboard/"]
+    Features --> Timeline["timeline/"]
+    Features --> Shared["shared/\n(cross-cutting)"]
+
+    S3 --> Layers["lib/\nservices/\nuse-cases/\ncomponents/\ni18n/\ntypes/"]
+```
+
+### Layer responsibilities
+
+| Layer | Purpose |
+|-------|---------|
+| `lib/` | AWS SDK client instantiation and low-level API wrappers (server-side only) |
+| `services/` | Business logic that composes `lib/` calls |
+| `use-cases/` | Application-level orchestration; called from Server Components or Route Handlers |
+| `components/` | React components — Server Components by default, Client Components only when interactivity requires it |
+| `i18n/` | Translation keys and locale-specific strings for this feature |
+| `types/` | TypeScript types shared within the feature |
+| `stores/` | Zustand stores for feature-local client UI state (present in some features) |
+
+### Adding a new feature slice
+
+When integrating a new AWS service, create `features/{service}/` and populate the layers you need. Not every layer is required — start with `lib/`, `use-cases/`, and `components/`. Add `services/` when business logic grows.
+
+---
+
+## AWS SDK boundary
+
+The AWS SDK is **server-side only**. This is an architectural constraint, not a preference.
+
+**Why**: The browser has no secure path to AWS credentials. Exposing credentials to the client is a security vulnerability. Even for local emulators with dummy credentials, the app follows the same rule to ensure the pattern is safe in any environment.
+
+**Where**: SDK clients are initialized in `lib/aws/config.ts` (shared config) and `features/{service}/lib/` (per-feature clients). They are imported only in:
+- Server Components (files without `"use client"`)
+- Route Handlers (`app/api/**`)
+- `use-cases/` and `services/` layers (which are called from the above)
+
+Client Components receive serialized data passed down as props or fetched via Route Handlers.
+
+---
+
+## i18n routing
+
+The app uses Next.js App Router's locale-based routing. All pages live under `app/[lang]/`:
+
+```
+app/
+└── [lang]/
+    ├── page.tsx          ← locale-aware home
+    ├── s3/page.tsx
+    ├── sqs/page.tsx
+    └── ...
+```
+
+- Supported locales are defined in the shared i18n configuration.
+- The `[lang]` segment is resolved at request time by the middleware.
+- Fallback locale is `en` — requests without a locale prefix are redirected.
+- Translation strings live in `features/{service}/i18n/` (feature-scoped) and `features/shared/i18n/` (global strings).
+
+---
+
+## State management
+
+**Zustand** is used for client UI state. Two placement rules apply:
+
+| Store location | Use for |
+|---------------|---------|
+| `features/shared/stores/` | UI state shared across features (e.g. mobile nav open/close, active profile) |
+| `features/{service}/stores/` | Feature-local state (e.g. CloudWatch Logs polling state, Inspector buffer) |
+
+Server state (data from AWS) is NOT stored in Zustand. It is fetched server-side and passed as props or streamed via RSC.
+
+---
+
+## Key patterns
+
+- **RSC-first**: all components are Server Components by default. Add `"use client"` only when you need browser APIs, event handlers, or hooks.
+- **Server Actions for mutations**: form submissions and write operations use Next.js Server Actions rather than client-side fetch calls.
+- **Responsive design tokens**: Tailwind v4 theme tokens are defined in `app/globals.css` (`@theme inline`). Do not add custom breakpoint config files — extend the theme there.
+- **Docker output**: the app builds as a Next.js standalone output, suitable for the published Docker image.
+
+---
+
+## Cross-cutting features
+
+Some features are not AWS-service-specific but span the whole application:
+
+| Feature | Purpose |
+|---------|---------|
+| `inspector` | Request/response inspector for AWS SDK calls; buffer managed server-side |
+| `snapshots` | Save and restore AWS resource state |
+| `terminal` | Embedded terminal for running CLI commands against the emulator |
+| `seed` | Preset data seeding for LocalStack / Floci environments |
+| `config` | Application configuration management |
+| `timeline` | Event timeline across AWS services |
+| `shared` | Common components, hooks, stores, utilities, and i18n strings |

docs/contributing.md

@@ -0,0 +1,127 @@
+# Contributing
+
+Thanks for contributing to this project! This guide covers the development workflow, commit conventions, testing requirements, and PR guidelines.
+
+---
+
+## Prerequisites
+
+Follow [Getting Started](./getting-started.md) first to get a working local environment. Come back here once `pnpm dev` and `pnpm test` both run without errors.
+
+---
+
+## Local setup
+
+1. Fork the repository on GitHub.
+2. Clone your fork and add the upstream remote:
+   ```bash
+   git clone https://github.com/<your-username>/aws-local-ui.git
+   cd aws-local-ui
+   git remote add upstream https://github.com/sisques-labs/aws-local-ui.git
+   ```
+3. Install dependencies:
+   ```bash
+   pnpm install
+   ```
+4. Branch from `dev` — never from `main`:
+   ```bash
+   git checkout dev
+   git pull upstream dev
+   git checkout -b feat/my-feature
+   ```
+
+---
+
+## Branching strategy
+
+| Branch pattern | Purpose |
+|---------------|---------|
+| `feat/*` | New features |
+| `fix/*` | Bug fixes |
+| `chore/*` | Maintenance, dependency updates, docs |
+
+All pull requests target `dev`. The `dev` branch merges into `main` on release. Never open a PR directly against `main`.
+
+---
+
+## Commit conventions
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/).
+
+**Format**: `<type>(<scope>): <subject>`
+
+**Examples**:
+```
+feat(s3): add bucket creation dialog
+fix(logs): prevent duplicate polling on reconnect
+chore(deps): update vitest to 3.x
+docs(contributing): add responsive UI section
+```
+
+**Rules**:
+- Use the imperative mood in the subject ("add", not "added" or "adds")
+- Keep the subject under 72 characters
+- Reference related issues in the body when relevant: `Closes #123`
+- **`Co-Authored-By` and AI attribution lines are prohibited** — do not add them to any commit message
+
+---
+
+## Testing
+
+This project uses **Vitest** in strict TDD mode.
+
+```bash
+pnpm test        # run all tests
+pnpm test --ui   # open Vitest UI
+```
+
+Rules:
+- All tests must pass before opening a PR (`pnpm test` exits 0)
+- New features and bug fixes require corresponding tests
+- Tests live next to the files they test (e.g. `lib/aws/config.test.ts` alongside `lib/aws/config.ts`)
+- Do not add `it.skip` or `test.skip` without a linked issue explaining why
+
+---
+
+## Linting and formatting
+
+```bash
+pnpm lint      # ESLint
+pnpm format    # Prettier
+```
+
+Both run automatically on staged files via husky + lint-staged on commit. Fix any errors before pushing.
+
+---
+
+## Responsive UI requirements
+
+All new screens and components must work from narrow mobile (~375px) up to desktop:
+
+- **Minimum viewport**: 375px — test at this width before opening a PR
+- **Touch targets**: primary interactive elements must be at least **44×44px** (`min-h-11 min-w-11` before any `md:` override)
+- **Layout pattern**: prefer `flex-col` with `sm:` or `md:` row layouts for toolbars
+- **Table columns**: hide non-essential columns below `sm:` breakpoint
+- **Theme tokens**: Tailwind v4 tokens are defined in `app/globals.css` (`@theme inline`) — do not add custom breakpoint config files
+
+---
+
+## Next.js conventions
+
+Before writing any Next.js code, **read the relevant guide** in `node_modules/next/dist/docs/`. This version of Next.js has breaking changes — APIs and conventions may differ from your training data or prior experience. Heed deprecation notices.
+
+---
+
+## PR guidelines
+
+- Keep PRs focused and small — aim for ~400 changed lines or fewer
+- Use a descriptive title following the Conventional Commits format
+- Link related issues in the PR description (`Closes #109`)
+- Fill in the PR template if one is present
+- Do not merge your own PRs — wait for at least one review
+
+---
+
+## AI agent collaboration
+
+If you are an AI agent contributing to this project, [AGENTS.md](../AGENTS.md) is the authoritative source for conventions that apply to you — including tool use, file structure, state management, and testing rules. This guide summarizes conventions for human contributors; `AGENTS.md` covers agent-specific behavior in full detail.