Repository Structure

Comprehensive guide to understanding and navigating the Solana App Kit codebase organization

This document provides a comprehensive overview of how the Solana App Kit codebase is organized. Understanding this structure will help you navigate the project efficiently and know exactly where to make changes for your specific needs.

Root Directory Overview

solana-app-kit/
├── src/                    # Mobile app source code
├── server/                 # Backend server
├── android/                # Android-specific files
├── ios/                    # iOS-specific files
├── docs/                   # Documentation
├── scripts/                # Build and utility scripts
├── App.tsx                 # Main app component
├── package.json            # Dependencies and scripts
└── Configuration files     # Various config files

Monorepo Structure: The kit combines mobile app, backend server, and documentation in a single repository for easier development and maintenance

Mobile App Structure (src/)

The mobile application is organized into several key directories, each serving a specific purpose:

Core Features

src/core/ - Essential app functionality used across multiple screens

src/core/
├── chat/                   # AI chat integration
├── dev-mode/              # Development tools and debugging
├── profile/               # User profile management
├── shared-ui/             # Reusable UI components
└── thread/                # Social feed and threading

Chat

AI chat integration with Solana blockchain interactions

Dev Mode

Development tools for debugging and testing

Profile

User profile management and account settings

Shared UI

Reusable components used throughout the application

Thread

Social feed and threading for community features

Purpose: Core features are central to the app’s functionality and provide shared capabilities across multiple screens and modules.

Backend Server Structure (server/)

The backend server provides essential API endpoints and services:

server_structure · object

Show 🗄️ Server Directory Structure

server/
├── src/
│   ├── controllers/       # Request handlers
│   ├── routes/            # API endpoint definitions
│   ├── service/           # Business logic
│   ├── db/                # Database configuration
│   ├── types/             # TypeScript interfaces
│   └── utils/             # Server utilities
├── package.json           # Server dependencies
└── .env.example           # Environment template

Purpose: The server handles blockchain operations, data persistence, external API integrations, and provides enhanced functionality for the mobile app.

Platform-Specific Directories

iOS Directory

ios/ - iOS-specific configuration and native code

ios/
├── SolanaAppKit/          # Main iOS project
│   ├── Info.plist         # iOS app configuration
│   ├── AppDelegate.mm     # iOS app delegate
│   └── Images.xcassets/   # iOS app icons and images
├── Podfile                # CocoaPods dependencies
└── SolanaAppKit.xcworkspace # Xcode workspace

iOS Development: Requires macOS and Xcode for building and testing on iOS devices

Configuration Files

Key configuration files in the root directory:

App.tsx

Main React Native component and app initialization entry point

package.json

Project dependencies, scripts, and metadata configuration

app.config.js

Expo configuration for builds, deployment, and app settings

babel.config.js

JavaScript compilation configuration and plugin setup

metro.config.js

Metro bundler configuration for React Native builds

tsconfig.json

TypeScript compiler configuration and type checking rules

.env.local

Environment variables (not in repo, created during setup)

mint.json

Documentation configuration for this documentation site

Module Architecture Pattern

Each module follows a consistent, well-defined structure:

Module Structure

module-name/
├── components/            # UI components specific to this module
├── hooks/                 # Custom hooks for module functionality
├── screens/               # Screens specific to this module
├── services/              # API and blockchain services
├── types/                 # TypeScript interfaces
├── utils/                 # Utility functions
├── index.ts               # Public API exports
└── README.md              # Module documentation

This pattern ensures:

Consistency

Similar organization across all modules makes navigation predictable

Encapsulation

Module internals are contained with clean public interfaces

Reusability

Clean public APIs make modules easy to integrate and reuse

Maintainability

Easy to understand and modify with clear separation of concerns

Data Flow Architecture

Understanding how components connect and data flows through the application:

1. Component Hierarchy

   Screens import and use Components from modules for UI composition

2. State Management

   Components use Hooks for state management and business logic

3. External Operations

   Hooks call Services for API interactions and blockchain operations

4. Utility Functions

   Services use Utils for common operations and data processing

5. Type Safety

   Everything uses Types for TypeScript type safety and IntelliSense

Data Flow Diagram

Development Workflow

Understanding the structure helps with common development tasks:

development_workflow · object

Show 🔧 Adding New Features

1. Create or extend modules in src/modules/ for protocol integrations
2. Add components within the relevant module’s components/ directory
3. Create hooks for business logic in the module’s hooks/ directory
4. Update module exports in index.ts to expose new functionality

Show 🎨 UI Changes

1. Modify components within relevant modules for feature-specific UI
2. Update shared components in src/core/shared-ui/ for common elements
3. Adjust styles using the design system in src/assets/
4. Test across platforms to ensure consistent appearance

Show 📱 New Screens

1. Add screens to src/screens/ organized by feature area
2. Update navigation configuration in src/shared/navigation/
3. Add routing for deep linking and navigation flows
4. Test navigation on both iOS and Android platforms

Show 🔌 API Integration

1. Extend services in modules for protocol-specific integrations
2. Add shared services in src/shared/services/ for common APIs
3. Update types to include new API response interfaces
4. Add error handling and status management

Show 🏪 State Changes

1. Update Redux slices in src/shared/state/ for global state
2. Add module-specific state using local hooks when appropriate
3. Implement persistence for important user data
4. Test state synchronization across components

Best Practices

Module Independence

Keep modules loosely coupled to maintain modularity and testability

Shared Code

Put common functionality in src/shared/ for reusability across modules

Type Safety

Define interfaces in module types/ directories for better developer experience

Export Consistency

Use index.ts files for clean public APIs and easier imports

Documentation

Update module READMEs when making changes to keep docs current

Testing

Write tests for critical business logic in services and hooks

Next Steps

Now that you understand the repository structure, explore these guides:

Assets Guide

Learn about the design system and asset management for consistent UI

Components Guide

Understand component architecture and reusable UI patterns

Configuration Guide

Configure the app and understand environment settings