Experimental. Every published package in this repository is experimental: its exports, build entries and files may change or be removed in any release, a minor one included. See Stability.
Table of Contents
🧱 The Stack
Toolchain
Frontend
Backend
Infrastructure
Hosting & Domain Providers
🏠 Local Development
Git configuration to enable symlinks
The projects make use of symlinks in the git project. On Windows, this may not work as expected without extra configuration. To configure git to create symlinks on windows, you need to enable the Windows "Developer Mode" setting, and also set the core.symlinks git feature using either of the following commands:
# Global setting
git config --global core.symlinks true
# Local setting
git config core.symlinks true
After applying this setting, you may need to reset your local branch to ensure the files get rewritten as symlinks. Note that this step is destructive and you will want to push any changes you have made prior to resetting your branch.
git reset --hard
Installing Dependencies
- Install the global Vite+ CLI, then the node and pnpm versions the repository pins:
vp env install
- Install Node Modules:
pnpm i
-
Install PostgreSQL + PgAdmin. On macOS, brew install postgresql@18 installs the server and brew services start postgresql@18 keeps it running across logins and reboots. Its binaries are in /opt/homebrew/opt/postgresql@18/bin, which is not on PATH until added. The server listens on localhost:5432. The esposter database holds no data worth keeping: pnpm dev runs the migrations on it.
-
Add .env file according to .env.example in apps/web directory.
-
Check what this machine still needs, the tools and logins with the command that installs or logs in to each:
pnpm ai:setup
Checkout the deployment documentation for more information.
Spotlight on macOS
The parity data lives in {data-root}/genshin-parity unless GENSHIN_PARITY_DIRECTORY names another folder. Create {data-root}.noindex as the data folder and make {data-root} a symlink to it: macOS never indexes a *.noindex folder and Spotlight follows no symlink, so every {data-root}/... path still resolves, and a real {data-root} folder must not be created beside the link. Then add node_modules and the pnpm store ({home}/Library/pnpm/store) under System Settings → Spotlight → Search Privacy, which can only be done by hand. The reason is in the machine efficiency design.
Development Server
- Build the packages to be used by the application:
vp run build:packages
- Change to the app directory:
cd apps/web
- Start the development server on http://localhost:3000
pnpm dev
Production
Build the application for production:
pnpm build
Locally preview production build:
pnpm -C apps/web preview
🧭 Architecture
Esposter is a pnpm workspaces monorepo. See monorepo tooling for workspace script orchestration and publishing boundaries.
Packages are used directly by the nuxt application via workspace:*.
How AI sessions land their commits, and how those commits are reviewed on the way to main, is in the review docs.
Workspace Graph
Each node's hue and tint are the role its edges give it, darkest at what the repo ships and lightest at what
the rest of it stands on; the key is drawn into the image.
Regenerate it from the repo root with:
pnpm graph:gen
📦 Packages
[!WARNING]
The published packages are built for this repository first. Use them at your own risk: their APIs may change in any release, without a deprecation period, in pursuit of better performance and simpler code.
| Package | Description | Published |
|---|
apps/functions | Serverless Azure Functions backend — push notifications, webhooks, EventGrid | — |
apps/infra | Pulumi infrastructure code and migration tools for Azure resources | — |
apps/web | Main Nuxt web application — frontend, server routes, tRPC API | — |
packages/agent-console-server | Agent console host — Claude Code sessions over a token-gated loopback WebSocket | ✓ |
packages/azure | Azure wire conventions — OData filter clauses, entity key casing, service limits | ✓ |
packages/azure-mock | Mock Azure service classes for local dev and testing | ✓ |
packages/configuration | Shared ESLint, TSConfig, and tsdown build configurations | — |
packages/db | Database connection utilities for Drizzle ORM, Azure Table, Blob, and WebPubSub | — |
|
🔌 Claude Code Plugins
This repository is also a Claude Code plugin marketplace named esposter, declared in .claude-plugin/marketplace.json. Anyone adds it by the repository's GitHub name and installs a plugin by its marketplace name:
claude plugin marketplace add Esposter/Esposter
claude plugin install genshin-persona@esposter
claude plugin install genshin-mods@esposter
| Plugin | What it does |
|---|
genshin-mods | Eight mods: five under one band above the prompt, waypoints (the next steps, one press each), resin (cache, context, limits and cost, with warm, compact and a one-click handoff), veil (recording mode), commission (a goal's task list and clock) and ward (a question before editing a file another session just changed), and three guards: a delegation guard that nudges a run of lookups toward a haiku agent, a disk-scan guard that refuses a Bash scan from a root or home folder, and a whole-index guard that refuses a git command over the whole index while another session shares the checkout. |
genshin-persona | Speaks as the Genshin Impact character whose birthday is nearest to today, with each answer opening on a spoken line and the rest in plain prose, and reads each reply aloud in the character's own cloned voice. |
A plugin here is an ordinary workspace package, so it is formatted, linted, tested and dependency-bumped with everything else, and a merge to main is its release: an installed copy follows the marketplace on the next plugin update. How that is built, and what it deliberately does not do, is on the Claude interface page.
🤝 Community
We welcome contributions from everyone and are committed to maintaining a friendly, safe, and welcoming community. Start with the Contributing guide, which also lists the recommended editor extensions. Please see our Code of Conduct and Security Policy for more information.
⚖️ License
This project is licensed under the Apache-2.0 license.
