League Concierge

A retrieval-augmented chatbot that answers members' questions from an organization's own documents: rulebooks, policies, and web pages. Members use it through a chat widget embedded in the organization's website. Administrators manage the documents through a web admin page; no command line is needed after setup.

It was built for the Oregon Youth Soccer Association (OYSA), where it runs at footy.oregonyouthsoccer.org as "Footy," a Sasquatch mascot. The code is MIT-licensed and you are welcome to fork it for your own organization. The OYSA branding is not licensed; see Rebranding a fork.

Features

• Chat widget served from its own subdomain and embedded with an <iframe>. Multi-turn conversation, answers cite their source documents, and users can rate answers thumbs-up/down with an optional comment.
• Answers come only from your documents. If the documents don't cover a question, the bot says so and points the user to the organization.
• Admin page (/admin):
  • Documents: upload PDF or Word (.docx) files, add up to 10 web page URLs at a time, refresh a web page, delete a source, and see how often each source has been cited.
  • Query Log: the 100 most recent questions and answers, filterable by rating, with a 30-day CSV export. Click a row to see the exchange as the user saw it; the trash icon permanently deletes it.
  • Audit: who added, updated, or removed each source, with a full CSV export.
• Admin sign-in with a one-time code emailed to addresses on an allowlist. No passwords.

How it works

your-org.example
  └── <iframe src="https://chat.your-org.example">
        └── Next.js app on Vercel
              ├── /          public chat UI
              ├── /admin     admin UI (emailed-code sign-in)
              └── /api/*     serverless routes
                    ├── OpenAI text-embedding-3-small   embeddings
                    ├── Pinecone serverless             vector search
                    ├── Anthropic Claude                answer generation
                    ├── Neon Postgres                   admins, sources, chat log, audit
                    └── Resend                          sign-in code email

Ingest. Text is extracted from the file or web page, split into ~400-token chunks with 50-token overlap, embedded, and stored in Pinecone. The source is registered in Neon.

Chat. The latest question is embedded and the 5 closest chunks are retrieved. Those chunks and the full conversation go to Claude, which answers using only that context. The reply and the documents it drew on are returned to the widget and logged.

Services you need

Service	Used for
Vercel	Hosting
OpenAI	Embeddings only
Anthropic	Answer generation (the main per-use cost)
Pinecone	Vector database
Neon	Postgres
Resend	Sign-in code email

All are required for a working deployment; free tiers are enough for a small organization except OpenAI and Anthropic, which bill per use. Chat runs without Neon, but nobody can sign in to add documents.

Getting started

DEPLOY.md walks through setup end to end: accounts, database, local run, Vercel deployment, embedding the widget, and troubleshooting.

Reference:

• docs/ADMIN_AUTH.md: admin sign-in, allowlist, audit log
• docs/DATABASE.md: Neon schema, what is logged, maintenance

Data handling

End users are anonymous. The chat page generates a session ID in browser memory when it loads; it is not stored in a cookie or browser storage and resets on refresh.

Every chat turn is stored in your Neon database: the question, the answer, the documents cited, the session ID, response time, and any rating and comment. IP addresses are not stored. There is no switch to turn chat logging off. Questions are also sent to OpenAI (to embed the question) and Anthropic (to generate the answer), and are subject to their data policies.

For administrators, the database stores email, name, phone number, sign-in times, and the audit trail of their source changes.

The chat page links to a privacy policy at /privacy (app/privacy/page.tsx). It is written for OYSA; rewrite it for your organization, including the effective date. The contact address comes from the PRIVACY_CONTACT_EMAIL env var.

Security

• /api/chat and /api/rate are public by design, and every chat call costs OpenAI and Anthropic credit. Add a rate limit (for example a Vercel Firewall rule) before linking the widget from a public page.
• Admin routes require a signed-in admin on ADMIN_ALLOWLIST. The URL ingest feature fetches any URL an admin enters, so keep the allowlist tight.
• The admin page cannot be framed; the chat page can be framed only by the origins listed in next.config.ts.

Development

npm install
npm run dev            # http://localhost:3000 and /admin
npm run lint
npm run build
npm run smoke          # checks OpenAI, Pinecone, and Anthropic credentials

Scripts read .env.local. Without Resend configured, sign-in codes are printed to the dev server log.

This is the beginning of the README. Read the rest at the original. Read the full README ↗