📁 Code Organization & Structure
This document provides a comprehensive guide to the MyPit platform's codebase organization, explaining the purpose and structure of each directory and key files.
📖 Project Structure Overview
mypit_core/
├── 📁 app/ # Next.js 15 App Router pages
├── 📁 components/ # Reusable React components
├── 📁 convex/ # Backend Convex functions & schema
├── 📁 hooks/ # Custom React hooks
├── 📁 lib/ # Utility libraries
├── 📁 smart_contracts/ # Ethereum smart contracts implementation
├── 📁 jwtoken_web_test/ # JWT token testing utilities
├── 📄 package.json # Dependencies & scripts
├── 📄 next.config.js # Next.js configuration
├── 📄 convex.config.ts # Convex configuration
├── 📄 middleware.ts # Next.js middleware
└── 📄 tailwind.config.ts # Tailwind CSS configuration🌐 Frontend Organization (/app)
The Next.js App Router structure provides a file-system based routing mechanism with enhanced features.
Route Structure
app/
├── 📄 layout.tsx # Root layout wrapper
├── 📄 page.tsx # Home page component
├── 📄 globals.css # Global styles
├── 📄 global-error.tsx # Global error boundary
├── 📄 middleware.ts # Route-level middleware
│
├── 📁 auth/ # Authentication flows
│ ├── 📁 login/
│ │ ├── 📄 page.tsx # Login page
│ │ └── 📄 layout.tsx # Auth layout
│ └── 📁 signup/
│ ├── 📄 page.tsx # Registration page
│ └── 📄 components/ # Auth-specific components
│
├── 📁 dashboard/ # Main dashboard interface
│ ├── 📄 page.tsx # Dashboard home
│ ├── 📄 layout.tsx # Dashboard layout
│ └── 📁 classes/ # Educational features
│ ├── 📄 page.tsx # Classes overview
│ └── 📁 [classId]/ # Dynamic class pages
│
├── 📁 document/ # Document management
│ └── 📁 [docID]/ # Dynamic document viewer
│ ├── 📄 page.tsx # Document display
│ └── 📄 loading.tsx # Loading state
│
├── 📁 sandbox/ # Sandbox environments
│ └── 📁 [id]/ # Dynamic sandbox instances
│ ├── 📄 page.tsx # Sandbox interface
│ └── 📄 error.tsx # Error handling
│
├── 📁 role-application/ # Role request flows
│ ├── 📄 page.tsx # Application form
│ └── 📁 login/ # Auth-required flow
│
├── 📁 payment/ # Payment processing
│ ├── 📄 page.tsx # Payment interface
│ └── 📄 style.css # Payment-specific styles
│
├── 📁 verify/ # Verification flows
│ └── 📁 badge/ # Badge verification
│ └── 📄 page.tsx # Verification interface
│
├── 📁 collection/ # Badge collections
│ └── 📁 [collection]/ # Dynamic collection pages
│
├── 📁 classDetails/ # Detailed class information
│ └── 📁 [classId]/ # Dynamic class details
│
├── 📁 classEnrollment/ # Class enrollment flows
│ ├── 📁 [code]/ # Enrollment by code
│ └── 📁 login/ # Auth-required enrollment
│
├── 📁 success/ # Success pages
├── 📁 error/ # Error pages
└── 📁 public/ # Static assets
└── 📄 google-icon.svg # OAuth provider iconsPage Component Structure
typescript
// Example: app/dashboard/page.tsx
import { Metadata } from 'next';
import { redirect } from 'next/navigation';
import { getCurrentUser } from '@/convex/auth';
import DashboardComponent from '@/components/dashboard/holder-dashboard';
export const metadata: Metadata = {
title: 'Dashboard | MyPit',
description: 'Manage your badges and credentials',
};
export default async function DashboardPage() {
const user = await getCurrentUser();
if (!user) {
redirect('/auth/login');
}
return (
<div className="container mx-auto py-6">
<DashboardComponent user={user} />
</div>
);
}🧩 Components Organization (/components)
Organized by feature domains with shared UI components at the root level.
Component Hierarchy
components/
├── 📄 TextEditor.tsx # Rich text editor (Quill.js)
│
├── 📁 ui/ # ShadCN UI components
│ ├── 📄 button.tsx # Base button component
│ ├── 📄 input.tsx # Form input component
│ ├── 📄 dialog.tsx # Modal dialog component
│ ├── 📄 alert.tsx # Alert/notification component
│ ├── 📄 avatar.tsx # User avatar component
│ ├── 📄 badge.tsx # Badge display component
│ ├── 📄 card.tsx # Card container component
│ ├── 📄 dropdown-menu.tsx # Dropdown menu component
│ ├── 📄 form.tsx # Form wrapper component
│ ├── 📄 label.tsx # Form label component
│ ├── 📄 select.tsx # Select dropdown component
│ ├── 📄 separator.tsx # Visual separator component
│ ├── 📄 sheet.tsx # Side panel component
│ ├── 📄 skeleton.tsx # Loading skeleton component
│ ├── 📄 table.tsx # Data table component
│ ├── 📄 tabs.tsx # Tab navigation component
│ ├── 📄 toast.tsx # Toast notification component
│ └── 📄 tooltip.tsx # Tooltip component
│
├── 📁 convexProvider/ # Convex integration
│ └── 📄 ConvexProvider.tsx # Convex client provider
│
├── 📁 customHooks/ # Reusable custom hooks
│ └── 📄 queryWithStatus.tsx # Query state management
│
├── 📁 types/ # TypeScript type definitions
│ └── 📄 userTypes.ts # User-related types
│
├── 📁 dashboard/ # Dashboard components
│ ├── 📄 header.tsx # Dashboard header
│ ├── 📄 sidebar.tsx # Navigation sidebar
│ ├── 📄 notifications.tsx # Notification panel
│ ├── 📄 profile-settings.tsx # User profile settings
│ ├── 📄 user-management-dashboard.tsx # Admin user management
│ │
│ ├── 📄 holder-dashboard.tsx # Badge holder interface
│ ├── 📄 issuer-dashboard.tsx # Badge issuer interface
│ ├── 📄 verifier-dashboard.tsx # Badge verifier interface
│ ├── 📄 data-consumer-dashboard.tsx # Data consumer interface
│ │
│ ├── 📁 classes/ # Educational components
│ ├── 📁 holder/ # Holder-specific components
│ ├── 📁 issuer/ # Issuer-specific components
│ ├── 📁 verifier/ # Verifier-specific components
│ ├── 📁 data-consumer/ # Data consumer components
│ ├── 📁 navigation/ # Navigation components
│ └── 📁 sandbox/ # Sandbox components
│
├── 📁 purchase/ # Payment components
│ ├── 📄 Purchase.tsx # Payment form
│ └── 📄 style.css # Payment styles
│
└── 📁 sandbox/ # Sandbox components
├── 📄 CodeRunner.tsx # Code execution interface
├── 📄 Select.tsx # Sandbox selector
└── 📄 style.css # Sandbox stylesComponent Design Patterns
Compound Components
typescript
// components/ui/card.tsx
const Card = React.forwardRef<HTMLDivElement, CardProps>(
({ className, ...props }, ref) => (
<div
ref={ref}
className={cn("rounded-lg border bg-card text-card-foreground shadow-sm", className)}
{...props}
/>
)
);
const CardHeader = React.forwardRef<HTMLDivElement, CardHeaderProps>(
({ className, ...props }, ref) => (
<div
ref={ref}
className={cn("flex flex-col space-y-1.5 p-6", className)}
{...props}
/>
)
);
export { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter };Feature Components
typescript
// components/dashboard/holder-dashboard.tsx
interface HolderDashboardProps {
user: User;
badges?: Badge[];
classes?: Class[];
}
export default function HolderDashboard({ user, badges, classes }: HolderDashboardProps) {
const [activeTab, setActiveTab] = useState('badges');
return (
<div className="space-y-6">
<DashboardHeader user={user} />
<Tabs value={activeTab} onValueChange={setActiveTab}>
<TabsList>
<TabsTrigger value="badges">My Badges</TabsTrigger>
<TabsTrigger value="classes">Enrolled Classes</TabsTrigger>
<TabsTrigger value="requests">Access Requests</TabsTrigger>
</TabsList>
<TabsContent value="badges">
<BadgeGrid badges={badges} />
</TabsContent>
<TabsContent value="classes">
<ClassList classes={classes} />
</TabsContent>
<TabsContent value="requests">
<RequestsPanel />
</TabsContent>
</Tabs>
</div>
);
}Custom Hooks Pattern
typescript
// components/customHooks/queryWithStatus.tsx
export function useQueryWithStatus<T>(
query: FunctionReference<"query", any, T>,
args?: any
) {
const [status, setStatus] = useState<'loading' | 'success' | 'error'>('loading');
const data = useQuery(query, args);
useEffect(() => {
if (data !== undefined) {
setStatus('success');
}
}, [data]);
return { data, status, isLoading: status === 'loading' };
}⚙️ Backend Organization (/convex)
Convex functions organized by feature domain with shared utilities and configurations.
Backend Structure
convex/
├── 📄 _generated/ # Auto-generated Convex types
├── 📄 convex.config.ts # Convex configuration
├── 📄 schema.ts # Database schema definitions
├── 📄 auth.config.ts # Authentication configuration
├── 📄 auth.ts # Authentication functions
├── 📄 http.ts # HTTP endpoints
├── 📄 crons.ts # Scheduled job definitions
├── 📄 triggers.ts # Database triggers
├── 📄 index.ts # Main exports
├── 📄 rateLimiter.ts # Rate limiting utilities
├── 📄 storage.ts # File storage functions
├── 📄 messages.ts # Messaging system
├── 📄 presence.ts # Real-time presence
├── 📄 documents.ts # Document management
├── 📄 documentViews.ts # Document viewing logic
├── 📄 teams.ts # Team management
├── 📄 teamsAdmin.ts # Team administration
├── 📄 user.ts # User management functions
├── 📄 sendEmails.ts # Email service integration
├── 📄 ResendOTP.ts # OTP email sending
├── 📄 ResendOTPPasswordReset.ts # Password reset emails
│
├── 📁 admin/ # Administrative functions
│ ├── 📄 adminActions.ts # Admin actions features: actions are external API calls
│ ├── 📄 adminMutations.ts #Admin Mutation features
│
├── 📁 holder/ # Badge holder functions
│ ├── 📄 holderActions.ts # External and internal API calls
│ ├── 📄 holderMutation.ts # Database mutations
│ ├── 📄 holderQueries.ts # Database queries
│
├── 📁 issuer/ # Badge issuer functions
│
├── 📁 verifier/ # Badge verifier functions
│
├── 📁 consumer/ # Data consumer functions
│
├── 📁 features/ # Platform additional features
│
├── 📁 ai_features/ # AI security module
│
├── 📁 blockchain_module/ # Blockchain integration
├── 📁 did_module/ # DID management
├── 📁 sandbox_module/ # Sandbox system
├── 📁 shamir_secret/ # Shamir's Secret Sharing
├── 📁 jwt_web/ # JWT token management
└── 📁 openAPI/ # Exposed API endpoints