innozverse Repository Structure Skill

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:

import { 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:

import { ApiClient } from '@innozverse/​api-client';
const 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:

// tsconfig.json
{
  "extends": "@innozverse/​config/​tsconfig.base.json"
}

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

// ✅ Use package name
import { HealthResponse } from '@innozverse/​shared';

// ❌ Don't use relative paths across packages
import { HealthResponse } from '../​../​../​packages/​shared/​src/​types';

Within the Same Package

// ✅ Use relative imports
import { helper } from './​utils/​helper';

// ❌ Don't use absolute package imports for same package
import { helper } from '@innozverse/​shared/​utils/​helper';

Next.js @ Alias

// In apps/​web only
import { 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

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

Apps Can Import from Packages

// ✅ This is fine
import { HealthResponse } from '@innozverse/​shared';

Packages Can Import from Other Packages

// ✅ This is fine (with workspace dependency)
import { 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)