Project Structure

hh-felidae/
├── apps/                    # Main applications
│   ├── jaguar/              # Nuxt frontend
│   │   ├── app/
│   │   │   ├── components/  # Vue components
│   │   │   ├── composables/ # Vue composables
│   │   │   ├── layouts/     # Page layouts
│   │   │   ├── libraries/   # Client utilities
│   │   │   ├── middleware/  # Route middleware
│   │   │   ├── pages/       # File-based routing
│   │   │   └── plugins/     # Nuxt plugins
│   │   ├── public/          # Static assets
│   │   └── server/          # Server-side code
│   │
│   ├── puma/                # Fastify backend (search/ranking)
│   │   └── src/
│   │       ├── config/      # Environment and app config
│   │       ├── graphql/     # Schema, resolvers, generated types
│   │       ├── indexes/     # OpenSearch index definitions
│   │       ├── libraries/   # External service clients
│   │       ├── plugins/     # Fastify plugins (autoloaded)
│   │       ├── routes/      # REST endpoints (autoloaded)
│   │       ├── services/    # Business logic by domain
│   │       ├── types/       # TypeScript declarations
│   │       └── utils/       # Helper functions
│   │
│   └── tiger/               # Fastify backend (data/recommendations)
│       └── src/             # Same structure as puma
│           ├── scripts/     # Migration and backfill scripts
│           └── ...
│
├── pkgs/                    # Shared packages
│   ├── database/            # Drizzle schemas and migrations
│   │   ├── src/db1/         # MySQL schema (legacy)
│   │   ├── src/db2/         # PostgreSQL schema (growthbook)
│   │   └── src/db3/         # PostgreSQL schema (tiger)
│   └── shared/              # Common utilities
│
├── appx/                    # Supporting services (Docker configs)
│   ├── growthbook/          # Feature flags
│   ├── kafka-akhq/          # Kafka UI
│   ├── kafka-connector/     # Kafka S3 connector
│   ├── metarank/            # Recommendations
│   └── opensearch/          # Search engine
│
├── tools/                   # HTTP request files for testing APIs
├── docs/                    # Documentation and diagrams
├── scripts/                 # Shell scripts and configs
└── temp/                    # Temporary files (gitignored content)

Conventions

Backend Apps (Puma/Tiger)

• Plugins: Auto-loaded from src/plugins/, register Fastify plugins
• Routes: Auto-loaded from src/routes/, define REST endpoints
• Services: Domain-organized business logic, not auto-loaded
• GraphQL: Schema-first with Mercurius, types generated via codegen

Package Naming

• Apps: @hh-felidae/{app-name}
• Packages: @hh-felidae/{pkg-name}

Database Naming

• db1: Legacy MySQL (read-only)
• db2: PostgreSQL for GrowthBook
• db3: PostgreSQL for Tiger app data