GroupScope

GroupScope is a standalone, self-hostable research group operations workspace for small research groups. It combines a Next.js operations console, a Postgres-backed datastore, configurable meeting/project workflows, and OpenAI-compatible agent wiring so a group can track work without baking private lab assumptions into the source code.

The goal is a reusable skeleton: public-safe application code in this repository, private group state in a configured datastore, and group-specific knowledge/checklists in local adapters or private skill packs.

Status

Initial public skeleton. The app includes:

• first-run setup wizard and local administrator account setup
• users, roles, profile settings, notification preferences, and audit log
• configurable branding, datastore paths, uploads, and skill roots
• project records, project updates, artifacts, comments, and planning briefs
• theme/meeting workflow configuration and reminder tooling
• chat sessions, shared sessions, mention notifications, and memory controls
• OpenAI-compatible chat and embedding model configuration
• pre-submission review harness and configurable group skills

Scope

The first target is a private, single-group deployment. Multi-tenant SaaS, billing, and public hosting are not part of the first release.

Safety Boundary

This repository should contain generic application code and public-safe demo data only. Private group material belongs in an external datastore or private configuration pack.

Do not commit secrets, real user data, uploads, logs, runtime state, or private knowledge-base exports.

Requirements

• Node.js 22.13 or newer
• npm
• Docker and Docker Compose for the local Postgres/pgvector service
• An OpenAI-compatible model provider for agent/chat features

Local Development

npm install
cp .env.example .env
npm run db:up
npm run web:dev

Open http://localhost:9999.

If no active administrator exists, GroupScope shows the setup wizard first. The wizard creates a temporary administrator; that administrator must sign in once and finish the account setup screen before the main workspace opens.

To reset a local development database back to the first-run wizard state:

npm run db:reset

Useful checks:

npm run typecheck
npm run web:build
npm run check:theme-meetings
npm run check:chat-zdr

Configuration

The setup wizard and Admin Settings write runtime settings for:

• product and group display names
• logo and home image URLs
• group timezone
• datastore and uploads directories
• skill directories and optional Git repository references
• OpenAI-compatible base URL and model names
• meeting workflow name, group count, weekday, time, duration, and recurrence

API keys should stay in local environment configuration or a secret store:

OPENAI_API_KEY=...

New deployments should use the GROUPSCOPE_* and OPENAI_* variables shown in .env.example.

Deployment

GroupScope is designed to run as a self-hosted Node.js service with Postgres. A minimal single-host deployment looks like this:

1. Provision Postgres with the pgvector extension.
2. Copy .env.example to .env and set production values.
3. Set a strong AUTH_SECRET.
4. Set DATABASE_URL to the production Postgres connection string.
5. Set OPENAI_API_KEY, OPENAI_BASE_URL if needed, and model names.
6. Point GROUPSCOPE_DATASTORE_DIR, GROUPSCOPE_UPLOADS_DIR, and GROUPSCOPE_SKILLS_DIR at persistent private storage.
7. Install and build the app.
8. Run the Next.js web service on port 9999 behind your reverse proxy.

Example:

npm ci
npm run web:build
npm run web:start

A local Docker Postgres service is available for development:

npm run db:up

For production, run Postgres, uploads, datastore files, logs, and backups outside the repository. Do not rely on the development Docker volume as your only backup.

Optional supporting services:

• npm run mail:up starts Mailpit for local email testing.
• npm run build && npm run start builds and starts the Mastra service if you run agent workflows separately from the Next.js web service.
• npm run theme-meeting:cron can be scheduled by your process manager or cron when automated meeting reminders are enabled.

UI

The web console is built with Tailwind CSS v4 and shadcn/ui, using a neutral base with a teal accent and the Geist typeface. See docs/design.md for the public design system and tokens. The current console uses shadcn components plus small shared primitives in app/console/primitives.tsx; avoid adding new legacy global CSS for app controls.

Acknowledgements

GroupScope is built with and inspired by open-source tools, including:

• Next.js and React for the web application.
• Mastra for agent/tool/workflow wiring.
• Postgres and pgvector for persistent data and vector search support.
• Tailwind CSS and shadcn/ui for the interface foundation.
• Radix UI primitives used by shadcn components.
• lucide-react for icons.
• Geist for the default typeface.

The dashboard shell and page layout direction were adapted from the MIT-licensed next-shadcn-admin-dashboard template by Mohammed Arham Khan. shadcn/ui, Geist, and that template are MIT-licensed.

License

MIT.