Skip to main content

Quick Start Guide

Get Simple Manager up and running on your device in under 5 minutes. This guide will walk you through starting the development server, running the app, and creating your first record.
Make sure you’ve completed the Installation steps before proceeding.

Start the Development Server

1

Navigate to Project Directory

Open your terminal and navigate to the project directory:
cd simple-manager-mobile
2

Start Expo Development Server

Start the Expo development server:
npm start
Or use the Expo CLI directly:
npx expo start
This will start Metro bundler and display a QR code in your terminal.
3

Choose Your Platform

You’ll see several options in the terminal:
  • Press i for iOS Simulator (macOS only)
  • Press a for Android Emulator
  • Press w for Web
  • Scan QR code with Expo Go app on your physical device

Run on Different Platforms

You can also use platform-specific commands to launch directly without the interactive menu.

iOS (macOS only)

npm run ios
This will:
  1. Start the Metro bundler
  2. Open iOS Simulator
  3. Build and install the app
  4. Launch Simple Manager

Android

npm run android
Make sure you have an Android emulator running or a physical device connected via USB with USB debugging enabled.

Web

npm run web
This will open the app in your default web browser at http://localhost:8081.

Physical Device with Expo Go

1

Install Expo Go

Download Expo Go from:
2

Connect to Same Network

Ensure your development machine and mobile device are on the same Wi-Fi network.
3

Scan QR Code

  • iOS: Open Camera app and scan the QR code from terminal
  • Android: Open Expo Go app and scan the QR code

Create Your First Record

Now that the app is running, let’s create your first record!
1

Open the App

You should see the Simple Manager home screen with the title “Simple Manager” and two input fields: Title and Type.
The database is automatically initialized when you first launch the app using expo-sqlite.
2

Enter Record Details

Fill in the form:
  • Title: Enter a name for your record (e.g., “John Doe”, “Morning Meeting”)
  • Type: Enter a category (e.g., “client”, “task”, “appointment”)
Titles must be unique and cannot exceed 50 characters. The app will validate this automatically.
3

Save the Record

Tap the “Guardar” (Save) button. You’ll see:
  • A success toast notification
  • Your new record appears in the list below
  • The form clears automatically
4

Manage Your Record

Each record card displays:
  • Title and type
  • Created/updated timestamps
  • Edit and Delete buttons
Try editing or deleting your record to explore the full functionality!

Understanding the Code

Here’s what happens when you create a record:

Using the useRecords Hook

Component Usage
import { useRecords } from "@/src/presentation/hooks/useRecords";

function MyComponent() {
  const { records, create, update, remove } = useRecords();
  
  // Create a new record
  const handleCreate = async () => {
    try {
      await create("New Client", "client");
      // Record is automatically added to the list
    } catch (error) {
      console.error(error);
    }
  };
  
  return (
    // Your UI here
  );
}

Record Creation Flow

The data flows through the clean architecture layers:
RecordService.create()
import * as Crypto from 'expo-crypto';

async create(title: string, type: string) {
  const now = new Date().toISOString();
  
  const record: Record = {
    id: Crypto.randomUUID(),      // Generate unique ID
    title,
    type,
    createdAt: now,
    updatedAt: now,
    isDeleted: false,             // Soft delete flag
  }
  
  await this.repository.create(record);
  return record;
}
Records are stored in a local SQLite database using expo-sqlite. All operations are offline-first - no internet connection required!

Record Interface

Every record follows this TypeScript interface:
Record Entity
export interface Record {
    id: string;              // UUID from expo-crypto
    title: string;           // Required, max 50 chars
    subtitle?: string;       // Optional
    metadata?: string;       // Flexible JSON storage
    type: string;           // Category/classification
    userId?: string;        // For multi-user support
    createdAt: string;      // ISO timestamp
    updatedAt: string;      // ISO timestamp
    isDeleted: boolean;     // Soft delete flag
}

Common Development Commands

Here are some useful commands for development:

Clear Cache and Restart

npx expo start -c
Use this when you encounter unexpected behavior or after installing new dependencies.

Run Linter

npm run lint
Check your code for style and potential issues.

Reset Project

npm run reset-project
This runs the reset script to clean up and reinitialize the project.

Next Steps

Architecture

Learn about the Clean Architecture structure and how the layers interact

Data Model

Explore the Record entity, database schema, and validation rules

Customization

Customize the UI, add new record types, and extend functionality

API Integration

Learn how to migrate from SQLite to a backend API

Troubleshooting

App Won’t Start

1

Clear Metro Cache

npx expo start -c
2

Reinstall Dependencies

rm -rf node_modules
npm install
3

Check Expo Version

Ensure you’re using Expo SDK ~54.0:
npx expo --version

Database Issues

If you’re having database-related issues:
  • The database is automatically created on first launch
  • Database file location: Device’s local storage (managed by expo-sqlite)
  • To reset: Uninstall the app and reinstall

Validation Errors

Common validation rules:
  • Title is required and cannot be empty
  • Title cannot exceed 50 characters
  • Title must be unique (case-insensitive)
  • Type is required

Need Help?

If you encounter issues not covered here, check the project’s GitHub issues or create a new one with details about your problem.

Build docs developers (and LLMs) love