innozverse Repository Structure Skill

When navigating and modifying the innozverse repository, follow these structure conventions.

Top-Level Structure

innozverse/
├── apps/                 # Applications
├── packages/             # Shared packages
├── docs/                 # Documentation
├── .claude/              # Claude AI skills
├── .github/              # GitHub workflows
├── package.json          # Root package.json
├── pnpm-workspace.yaml   # pnpm workspace config
├── turbo.json            # Turborepo config
└── README.md             # Main README

Apps Directory

apps/web (Next.js)

apps/web/
├── src/
│   └── app/              # App Router pages
│       ├── layout.tsx    # Root layout
│       ├── page.tsx      # Home page
│       └── globals.css   # Global styles
├── public/               # Static assets
├── next.config.js        # Next.js config
├── tsconfig.json         # TypeScript config
├── .eslintrc.json        # ESLint config
├── .env.example          # Environment template
└── package.json          # Package dependencies

Key Points:

• Use App Router (not Pages Router)
• Pages in src/app/
• Static files in public/
• Environment vars start with NEXT_PUBLIC_

apps/api (Fastify)

apps/api/
├── src/
│   ├── index.ts          # Server entry point
│   └── routes/
│       ├── health.ts     # Health check route
│       └── v1/           # Versioned API routes
│           └── index.ts  # v1 routes
├── Dockerfile            # Fly.io deployment
├── fly.toml              # Fly.io config
├── tsconfig.json         # TypeScript config
├── .eslintrc.js          # ESLint config
├── .env.example          # Environment template
└── package.json          # Package dependencies

Key Points:

• Routes organized by version (v1/, v2/)
• Health check at root level
• Dockerfile for Fly.io deployment
• Environment vars in .env (never commit)

apps/mobile (Flutter)

apps/mobile/
├── lib/
│   ├── main.dart         # App entry point
│   └── services/
│       └── api_service.dart  # API client
├── android/              # Android-specific
├── ios/                  # iOS-specific
├── pubspec.yaml          # Dart dependencies
├── README.md             # Mobile-specific docs
└── analysis_options.yaml # Dart linter config

Key Points:

• Main app in lib/main.dart
• Services in lib/services/
• Models in lib/models/ (when added)
• Widgets in lib/widgets/ (when added)

Packages Directory

packages/shared

packages/shared/
├── src/
│   ├── index.ts          # Main export
│   ├── types.ts          # Type definitions
│   ├── schemas.ts        # Zod schemas
│   └── constants.ts      # Shared constants
├── dist/                 # Compiled output (gitignored)
├── tsconfig.json
├── .eslintrc.js
└── package.json

Purpose: Domain types, Zod schemas, shared constants

Usage:

typescript
1import { HealthResponse, healthResponseSchema } from '@innozverse/shared';

packages/api-client

packages/api-client/
├── src/
│   └── index.ts          # API client implementation
├── dist/                 # Compiled output (gitignored)
├── tsconfig.json
├── .eslintrc.js
└── package.json

Purpose: Typed HTTP client for web app

Usage:

typescript
1import { ApiClient } from '@innozverse/api-client';
2const client = new ApiClient('http://localhost:8080');

packages/config

packages/config/
├── eslint-preset.js      # Shared ESLint config
├── tsconfig.base.json    # Base TypeScript config
└── package.json

Purpose: Shared tooling configuration

Usage:

json
1// tsconfig.json
2{
3  "extends": "@innozverse/config/tsconfig.base.json"
4}

Documentation

docs/
├── architecture.md       # System architecture
├── conventions.md        # Coding conventions
├── deployment-flyio.md   # Fly.io deployment
└── contracts.md          # API contracts strategy

File Naming Conventions

TypeScript

• Files: kebab-case.ts (e.g., api-client.ts)
• React Components: PascalCase.tsx (e.g., Button.tsx)
• Tests: *.test.ts or *.test.tsx
• Types: types.ts or <module>.types.ts

Dart

• Files: snake_case.dart (e.g., api_service.dart)
• Tests: *_test.dart

Configuration

• ESLint: .eslintrc.js or .eslintrc.json
• TypeScript: tsconfig.json
• Environment: .env.example (committed), .env (gitignored)

Where to Add New Code

New API Endpoint

apps/api/src/routes/v1/users.ts  # New endpoint file

Update apps/api/src/routes/v1/index.ts to register

New Shared Type

packages/shared/src/types.ts  # Add interface
packages/shared/src/schemas.ts  # Add Zod schema

Export from packages/shared/src/index.ts

New Web Page

apps/web/src/app/users/page.tsx  # New page at /users

New Mobile Screen

apps/mobile/lib/screens/users_screen.dart  # New screen

New Shared Utility

packages/shared/src/utils/helper.ts  # New utility

Export from packages/shared/src/index.ts

Import Paths

Within innozverse Packages

typescript
1// ✅ Use package name
2import { HealthResponse } from '@innozverse/shared';
3
4// ❌ Don't use relative paths across packages
5import { HealthResponse } from '../../../packages/shared/src/types';

Within the Same Package

typescript
1// ✅ Use relative imports
2import { helper } from './utils/helper';
3
4// ❌ Don't use absolute package imports for same package
5import { helper } from '@innozverse/shared/utils/helper';

Next.js @ Alias

typescript
1// In apps/web only
2import { Component } from '@/app/components/Component';

Build Artifacts

What's Gitignored

node_modules/
dist/
.next/
.turbo/
build/
.env
.env.local
*.log

What's Committed

src/
public/
package.json
tsconfig.json
.env.example
README.md

Scripts Organization

Root package.json

• dev: Run web + API
• build: Build all packages and apps
• lint: Lint everything
• test: Run all tests

Individual Packages

• dev: Start dev server
• build: Build package
• lint: Lint package
• typecheck: Type check

Adding New Packages

1. Create directory: mkdir packages/new-package
2. Initialize: cd packages/new-package && pnpm init
3. Name: Use @innozverse/ prefix
4. Add to workspace: Already covered by packages/* in pnpm-workspace.yaml
5. Build config: Copy tsconfig.json from similar package
6. Add scripts: build, lint, typecheck

Directory Depth Guidelines

Maximum Nesting

• Apps: 3-4 levels deep

  apps/web/src/app/users/[id]/page.tsx  ✅
  

• Packages: 2-3 levels deep

  packages/shared/src/utils/validation.ts  ✅
  

When to Create Subdirectories

• 3+ related files: Create a subdirectory
• Single file: Keep at current level
• Shared concern: Extract to utils/ or lib/

Module Boundaries

Apps Cannot Import from Other Apps

typescript
1// ❌ Never do this
2import { something } from '../../api/src/utils';

Apps Can Import from Packages

typescript
1// ✅ This is fine
2import { HealthResponse } from '@innozverse/shared';

Packages Can Import from Other Packages

typescript
1// ✅ This is fine (with workspace dependency)
2import { schema } from '@innozverse/shared';

Special Directories

.claude/skills/

AI agent instructions for project-specific patterns

.github/workflows/

GitHub Actions CI/CD pipelines

public/ (in apps/web)

Static assets served at root URL

dist/ (in packages)

Compiled TypeScript output (gitignored, created on build)