StratoFusion

Loading application...

StratoFusion

git clone https://github.com/your-org/stratofusion.git
cd stratofusion

pnpm env:guard
pnpm install

pnpm rclone:bootstrap
pnpm rclone:check

# Copy the main app template
cp .env.example.template .env.local

# Copy the Fly rclone template if you need the local service
cp fly-rclone/.env.example.template fly-rclone/.env

# App URLs
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Database (local isolated Neon database)
DATABASE_URL=postgresql://username:password@hostname/stratofusion-local?sslmode=require

# OAuth Configuration
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/google
ONEDRIVE_CLIENT_ID=your_onedrive_client_id
ONEDRIVE_CLIENT_SECRET=your_onedrive_client_secret
ONEDRIVE_REDIRECT_URI=http://localhost:3000/api/onedrive
DROPBOX_CLIENT_ID=your_dropbox_client_id
DROPBOX_CLIENT_SECRET=your_dropbox_client_secret
DROPBOX_REDIRECT_URI=http://localhost:3000/api/dropbox

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key

# Optional role assignments (server-only)
ADMIN_USER_IDS=user_admin_clerk_id
DEV_USER_IDS=user_dev_clerk_id

# Stripe (test mode locally)
NEXT_PUBLIC_STRIPE_ENABLED=true
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_FREE=price_...
STRIPE_PRICE_ID_PRO=price_...
STRIPE_PRICE_ID_UNLIMITED=price_...

# Rclone Service (optional for local dev)
FLYIO_RCLONE_SERVICE_URL=http://127.0.0.1:3001
NEXT_PUBLIC_FLYIO_RCLONE_SERVICE_URL=http://127.0.0.1:3001

# Cron Secret
CRON_SECRET=generate-a-unique-local-secret

# Sentry (server-side)
SENTRY_DSN=https://examplePublicKey@o0.ingest.us.sentry.io/0
# Optional; defaults to NODE_ENV
SENTRY_ENVIRONMENT=development
# Optional; defaults to VERCEL_GIT_COMMIT_SHA on Vercel
SENTRY_RELEASE=

# Push schema to the isolated local database
pnpm db:push

# Verify local environment isolation before starting the app
pnpm env:doctor:local

# (Optional) Open Drizzle Studio to view database
pnpm db:studio

pnpm dev

pnpm rclone:check
cd fly-rclone
node server.js

stripe listen --forward-to localhost:3000/api/webhooks/stripe

Pull latest changes
```
git pull origin dev
```

Create a feature branch from dev

git checkout dev
git checkout -b feature/your-feature-name

Make changes and test

pnpm dev          # Start dev server
pnpm test:watch   # Run tests in watch mode

Run quality checks

pnpm check        # Runs lint + typecheck
pnpm test         # Run all tests

Commit changes

git add .
git commit -m "feat: your feature description"

Push and create PR

git push origin feature/your-feature-name
# Create PR on GitHub

pnpm check        # Lint + TypeScript check
pnpm test         # All tests
pnpm format:write # Format code

stratofusion/
├── src/
│   ├── app/                # Next.js App Router (pages and API routes)
│   ├── components/         # React UI components
│   ├── contexts/           # State management contexts
│   ├── hooks/              # Custom React hooks
│   ├── infrastructure/     # Adapters for external infra (e.g., rclone)
│   ├── shared/             # Application-wide validation, builders, and errors
│   ├── services/           # Implementation logic
│   │   ├── adapters/       # Port implementations for cloud providers
│   │   └── base/           # Base service abstractions
│   ├── types/              # Domain ports and common type definitions
│   └── lib/                # General utility functions
├── public/                 # Static assets and Markdown docs
├── fly-rclone/             # Specialized transfer microservice
└── tests/                  # Mirror of src/ structure for testing

Component → Hook → API Route → Port (Interface) → Adapter (Implementation) → Cloud Provider API

// 1. Component uses hook
const { files, loading } = useDriveFiles(service, accountId, folderId);

Create component file

# For UI components
src/components/ui/MyComponent.tsx

# For feature components
src/components/MyFeatureComponent.tsx

Create Storybook story

src/components/ui/MyComponent.stories.tsx

Create tests
```
src/components/ui/MyComponent.test.tsx
```

Export from index (if needed)

// src/components/ui/index.ts
export { MyComponent } from "./MyComponent";

Create route file
```
src/app/api/my-endpoint/route.ts
```

Implement handler

import {
  createSuccessResponse,
  createErrorResponse,
} from "~/lib/api-response";

export async function GET(request: Request) {
  try {
    const data = await fetchData();
    return createSuccessResponse(data);
  } catch (error) {
    return createErrorResponse(error);
  }
}

Add tests
```
src/app/api/my-endpoint/route.test.ts
```

# Run all tests once
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with UI
pnpm test:ui

# Run tests with coverage
pnpm test:coverage

# Start Storybook dev server
pnpm storybook

# Build Storybook for deployment
pnpm build-storybook

Developer Onboarding

Developer Onboarding Guide

Table of Contents

Prerequisites

Required Software

Recommended VS Code Extensions

Required Accounts

Initial Setup

1. Clone the Repository

2. Verify The Native Shell And Install Dependencies

3. Bootstrap the Local rclone Binary on Windows

4. Set Up Environment Variables

5. Set Up Database

6. Start Development Servers

7. Verify Setup

Development Workflow

Daily Workflow

Pre-Commit Checklist

Project Structure

Key Directories

Important Files

Key Concepts

Service Abstraction Layer (Ports & Adapters)

Data Flow Pattern

State Management

Billing & Subscription Features

Key Components

Search Gating

Navigation

Common Tasks

Adding a New Component

Adding a New API Route

Adding a New Cloud Service

Running Tests

Running Storybook

Best Practices

Code Style

File Organization

Component Development

Testing

Git Workflow

Getting Help

Documentation

Team Resources

Common Issues