Repository Structure - Solana App Kit

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:

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/ - 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-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:

Component Hierarchy

Screens import and use Components from modules for UI composition

State Management

Components use Hooks for state management and business logic

External Operations

Hooks call Services for API interactions and blockchain operations

Utility Functions

Services use Utils for common operations and data processing

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

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

Show 🎨 UI Changes

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

Show 📱 New Screens

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

Show 🔌 API Integration

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

Show 🏪 State Changes

Update Redux slices in src/shared/state/ for global state
Add module-specific state using local hooks when appropriate
Implement persistence for important user data
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

Introduction

Getting Started

Using LLMs

Modules

Server

​Root Directory Overview

​Mobile App Structure (src/)

Chat

Dev Mode

Profile

Shared UI

Thread

​Backend Server Structure (server/)

​Platform-Specific Directories

​Configuration Files

App.tsx

package.json

app.config.js

babel.config.js

metro.config.js

tsconfig.json

.env.local

mint.json

​Module Architecture Pattern

Consistency

Encapsulation

Reusability

Maintainability

​Data Flow Architecture

​Data Flow Diagram

​Development Workflow

​Best Practices

Module Independence

Shared Code

Type Safety

Export Consistency

Documentation

Testing

​Next Steps

Assets Guide

Components Guide

Configuration Guide

Root Directory Overview

Mobile App Structure (`src/`)

Backend Server Structure (`server/`)

Platform-Specific Directories

Configuration Files

Module Architecture Pattern

Data Flow Architecture

Data Flow Diagram

Development Workflow

Best Practices

Next Steps