weseek__growi/apps/app/AGENTS.md

GROWI Main Application Development Guide

Overview

This guide provides comprehensive documentation for AI coding agents working on the GROWI main application (/apps/app/). GROWI is a team collaboration wiki platform built with Next.js, Express, and MongoDB.

Project Structure

Main Application (/apps/app/src/)

Directory Structure Philosophy

Feature-based Structure (Recommended for new features)

• features/{feature-name}/ - Self-contained feature modules
  • interfaces/ - Universal TypeScript type definitions
  • server/ - Server-side logic (models, routes, services)
  • client/ - Client-side logic (components, stores, services)
  • utils/ - Shared utilities for this feature
    

Important Directories Structure

• client/ - Client-side React components and utilities
• server/ - Express.js backend
• components/ - Universal React components
• pages/ - Next.js Pages Router
• states/ - Jotai state management
• stores/ - SWR-based state stores
• stores-universal/ - Universal SWR-based state stores
• styles/ - SCSS stylesheets with modular architecture
• migrations/ - MongoDB database migration scripts
• interfaces/ - Universal TypeScript type definitions
• models/ - Universal Data model definitions

Key Technical Details

Frontend Stack

• Framework: Next.js (Pages Router) with React
• Language: TypeScript (strict mode enabled)
• Styling: SCSS with CSS Modules by Bootstrap 5
• State Management:
  • Jotai (Primary, Recommended): Atomic state management for UI and application state
  • SWR: Data fetching, caching, and revalidation
  • Unstated: Legacy (being phased out, replaced by Jotai)
• Testing:
  • Vitest for unit tests (*.spec.ts, *.spec.tsx)
  • Jest for integration tests (*.integ.ts)
  • React Testing Library for component testing
  • Playwright for E2E testing
• i18n: next-i18next for internationalization

Backend Stack

• Runtime: Node.js
• Framework: Express.js with TypeScript
• Database: MongoDB with Mongoose ODM
• Migration System: migrate-mongo
• Authentication: Passport.js with multiple strategies (local, LDAP, OAuth, SAML)
• Real-time: Socket.io for collaborative editing and notifications
• Search: Elasticsearch integration (optional)
• Observability: OpenTelemetry integration

Common Commands

# Type checking only
cd apps/app && pnpm run lint:typecheck

# Run specific test file
turbo run test:vitest @apps/app -- src/path/to/test.spec.tsx

# Check migration status
cd apps/app && pnpm run dev:migrate:status

# Start REPL with app context
cd apps/app && pnpm run repl

Important Technical Specifications

Entry Points

• Server: server/app.ts - Handles OpenTelemetry initialization and Crowi server startup
• Client: pages/_app.page.tsx - Root Next.js application component
  • pages/[[...path]]/ - Dynamic catch-all page routes

---

This guide was compiled from project memory files to assist AI coding agents in understanding the GROWI application architecture and development practices.