This document provides a comprehensive overview of the project structure, file organization, and architectural decisions for the UmurSS7PCode educational simulation platform.
umurss7pcode/
├── public/ # Static assets
│ ├── vite.svg # Vite logo
│ └── favicon.ico # Application favicon
├── src/ # Source code
│ ├── components/ # React components
│ │ ├── ComponentDetails.tsx # Network component information panel
│ │ ├── Header.tsx # Application header with navigation
│ │ ├── NetworkTopologyView.tsx # Network topology main view
│ │ ├── NetworkVisualization.tsx # 3D network visualization
│ │ ├── SecurityAwareness.tsx # Security education module
│ │ ├── SMSFlowSimulator.tsx # SMS flow step-by-step simulator
│ │ └── SMSSimulationView.tsx # SMS simulation main view
│ ├── data/ # Static data and configurations
│ │ └── networkComponents.ts # SS7 network component definitions
│ ├── types/ # TypeScript type definitions
│ │ └── ss7.ts # SS7-related type definitions
│ ├── App.tsx # Main application component
│ ├── main.tsx # Application entry point
│ ├── index.css # Global styles and Tailwind imports
│ └── vite-env.d.ts # Vite environment type definitions
├── .gitignore # Git ignore rules
├── eslint.config.js # ESLint configuration
├── index.html # HTML entry point
├── package.json # Project dependencies and scripts
├── package-lock.json # Locked dependency versions
├── postcss.config.js # PostCSS configuration
├── tailwind.config.js # Tailwind CSS configuration
├── tsconfig.json # TypeScript configuration
├── tsconfig.app.json # TypeScript app-specific config
├── tsconfig.node.json # TypeScript Node.js config
├── vite.config.ts # Vite build configuration
├── README.md # Project documentation
└── structure.md # This file - project structure guide
The application follows a modular component architecture with clear separation of concerns:
App.tsx (Root Component)
├── Header.tsx (Navigation & Branding)
├── NetworkTopologyView.tsx (Network View Container)
│ ├── NetworkVisualization.tsx (3D Visualization)
│ └── ComponentDetails.tsx (Component Information)
├── SMSSimulationView.tsx (SMS Simulation Container)
│ ├── SMSFlowSimulator.tsx (Step-by-step Flow)
│ └── NetworkVisualization.tsx (Flow Visualization)
└── SecurityAwareness.tsx (Security Education)
Static Data (networkComponents.ts)
↓
Type Definitions (ss7.ts)
↓
Component State Management
↓
UI Components & Visualizations
↓
User Interactions & Animations
- Purpose: Main application component and routing logic
- Responsibilities:
- Tab-based navigation management
- View switching between Network, Simulation, and Security
- Global state management for active views
- Animation orchestration with Framer Motion
- Purpose: Application entry point and React DOM rendering
- Responsibilities:
- React StrictMode wrapper
- Root component mounting
- CSS imports and global styles
- Purpose: Application header with navigation and branding
- Features:
- Tab-based navigation system
- Brand identity with logo and description
- Active tab highlighting
- Responsive design for mobile/desktop
- Purpose: 3D interactive network topology visualization
- Technologies: Three.js, React Three Fiber, React Three Drei
- Features:
- 3D network node rendering with different colors per component type
- Interactive node selection and highlighting
- Connection line visualization between components
- Orbital camera controls for navigation
- Real-time animation and rotation effects
- Purpose: Detailed information panel for selected network components
- Features:
- Dynamic component information display
- Protocol listings and technical specifications
- Connection mapping and status indicators
- Animated transitions with Framer Motion
- Purpose: Step-by-step SMS message flow simulation
- Features:
- Interactive play/pause/reset controls
- Step-by-step progression through SMS routing
- Protocol identification for each step
- Visual progress indicators and completion states
- Detailed descriptions of each signaling step
- Purpose: Educational module for SS7 security vulnerabilities
- Features:
- Vulnerability categorization by severity
- Expandable vulnerability details
- Protection measure recommendations
- Educational disclaimers and external resources
- Purpose: Container component for network topology features
- Responsibilities:
- Component selection state management
- Connection highlighting coordination
- Layout management for visualization and details
- Purpose: Container component for SMS simulation features
- Responsibilities:
- Simulation step coordination
- Network highlighting during message flow
- Layout management for simulator and visualization
- Purpose: TypeScript type definitions for SS7 components and messages
- Definitions:
SS7Component: Network component structureSMSMessage: SMS message data structureSignalingStep: Individual signaling step definitionNetworkTopology: Complete network structure
- Purpose: Static data definitions for SS7 network components
- Content:
- Pre-defined SS7 components (MSC, HLR, VLR, SMSC, STP)
- Network topology with connections and protocols
- Component positioning for 3D visualization
- Purpose: Vite build tool configuration
- Settings:
- React plugin configuration
- Lucide React optimization exclusion
- Development server settings
- Purpose: Tailwind CSS framework configuration
- Settings:
- Content file scanning paths
- Theme extensions and customizations
- Plugin configurations
- Purpose: TypeScript compiler configuration
- Features:
- Strict type checking enabled
- Modern ES2020 target
- React JSX support
- Path resolution for imports
- Purpose: Code quality and linting configuration
- Rules:
- React hooks linting
- TypeScript-specific rules
- React refresh compatibility
- Primary: Cyan (#00ffff) - Active states and highlights
- Secondary: Blue variants - Protocol tags and information
- Success: Green - Completed states and security measures
- Warning: Yellow/Orange - Medium severity issues
- Error: Red - High severity vulnerabilities and critical states
- Neutral: Gray scale - Background, text, and inactive states
- Font Family: System fonts with fallbacks
- Headings: Bold weights for hierarchy
- Body Text: Regular weight for readability
- Code: Monospace for technical information
- Base Unit: 4px (Tailwind's default)
- Component Padding: 24px (p-6)
- Section Gaps: 24px (gap-6)
- Element Margins: 16px (mb-4, mt-4)
- Local State: React useState for component-specific state
- Prop Drilling: For simple parent-child communication
- Event Callbacks: For child-to-parent communication
- Page Transitions: Framer Motion AnimatePresence
- Component Animations: Individual motion.div components
- 3D Animations: Three.js useFrame hook for continuous animations
- Single Responsibility: Each component has one primary purpose
- Composition: Components are composed rather than inherited
- Type Safety: Full TypeScript coverage with strict settings
- react: Core React library
- react-dom: React DOM rendering
- three: 3D graphics library
- @react-three/fiber: React renderer for Three.js
- @react-three/drei: Three.js helpers and components
- framer-motion: Animation library
- lucide-react: Icon library
- typescript: Type checking and compilation
- vite: Build tool and development server
- tailwindcss: CSS framework
- eslint: Code linting
- @types/*: TypeScript type definitions
- Vite Dev Server: Fast HMR development server
- TypeScript Compilation: Real-time type checking
- Tailwind Processing: JIT compilation of CSS classes
- ESLint: Code quality checking
- TypeScript Build: Full type checking and compilation
- Vite Build: Optimized bundle creation
- Asset Optimization: Image and resource optimization
- Code Splitting: Automatic chunk splitting for performance
- Type Safety: Full TypeScript coverage
- Linting: ESLint for code quality
- Manual Testing: Interactive testing during development
- Unit Tests: Jest/Vitest for component testing
- Integration Tests: Testing component interactions
- E2E Tests: Playwright for full user journey testing
- Code Splitting: Automatic route-based splitting
- Lazy Loading: Dynamic imports for heavy components
- Memoization: React.memo for expensive components
- Asset Optimization: Vite's built-in optimizations
- Geometry Reuse: Shared geometries for similar components
- Texture Optimization: Efficient material usage
- Frame Rate Management: Controlled animation loops
- Export Functionality: PDF generation for network diagrams
- Advanced Simulations: More complex SS7 scenarios
- User Preferences: Customizable themes and settings
- Offline Support: Service worker for offline access
- State Management: Context API or Zustand for complex state
- Testing Suite: Comprehensive test coverage
- Performance Monitoring: Real-time performance metrics
- Accessibility: Enhanced ARIA support and keyboard navigation
This structure document serves as a living guide for understanding and contributing to the UmurSS7PCode project. It should be updated as the project evolves and new features are added.