CITIL - Institutional Asset & Workflow Management System

CITIL is a comprehensive React Native (Expo) mobile application designed to streamline institutional workflows, asset tracking, and procurement processes. It features a robust role-based access control system, offering tailored dashboards and capabilities for Staff, Head of Departments (HOD), Logistics, Finance, and Administrators.

📸 Screenshots

HOD Dashboard	Staff Dashboard	Finance Dashboard	Logistics Dashboard

(Screenshots represent the dynamic, role-based UI with neon-accented dark mode graphics.)

✨ Key Features

• Role-Based Workflows: Distinct interfaces and permissions for Staff, HOD, Finance, and Logistics personnel.
• Asset Lifecycle Management: Track assets from procurement to deployment, including QR-based scanning and location transfers.
• Procurement Pipeline: End-to-end request tracking, multi-level approvals (HOD -> Logistics -> Finance), and automated bill extraction logic.
• Real-time Notifications: In-app notification system for request updates, approvals, and system alerts.
• Offline & Demo Modes: Built-in resilient caching and a comprehensive Demo Mode featuring populated mock data for immediate exploration without backend dependencies.

🛠 Tech Stack

• Framework: React Native + Expo
• Navigation: React Navigation (Stack & Drawer)
• State Management: React Context API
• Backend / Database: Firebase Authentication & Firestore (with mock fallbacks)
• Styling: Custom StyleSheet system with a unified Dark Theme palette

---

🚀 Getting Started

Follow these steps to clone the repository, install dependencies, and run the application locally.

1. Prerequisites

Ensure you have the following installed on your local machine:

• Node.js (v18 or newer recommended)
• npm or Yarn
• Expo CLI (npm install -g expo-cli)
• Expo Go app installed on your physical iOS/Android device, OR an iOS Simulator / Android Emulator configured on your computer.

2. Clone the Repository

git clone https://github.com/yourusername/citil-mobile.git
cd citil-mobile

3. Install Dependencies

Using npm:

npm install

Or using yarn:

yarn install

4. Environment Variables

Create a .env file in the root directory of the project. You must define your Firebase configuration variables for the real backend to work.

If you just want to test the UI, the app will automatically fall back to Demo Mode if these are missing, injecting simulated offline data.

# Example .env configuration
EXPO_PUBLIC_FIREBASE_API_KEY=your_api_key
EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
EXPO_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
EXPO_PUBLIC_FIREBASE_APP_ID=your_app_id
EXPO_PUBLIC_API_URL=http://your_local_ip:5000/api

5. Run the Application

Start the Expo development server:

npx expo start

• Physical Device: Scan the QR code displayed in the terminal using the Expo Go app (on Android) or the default Camera app (on iOS).
• Simulator/Emulator: Press i to open in the iOS Simulator, or a to open in the Android Emulator.

🧪 Demo Mode Access

Use this section if you want to quickly access the app and understand exactly which mode you are using.

Demo Mode (for instant testing)

Use Demo Mode when you want to explore UI flows without setting up Firebase credentials.

1. Launch the app with npx expo start.
2. Open the app on device/emulator.
3. On the login screen, enable Demo Mode.
4. Sign in with one of the demo emails below.
5. Enter any password.

Demo Accounts:

• staff@citil.com
• hod@citil.com
• finance@citil.com
• logistics@citil.com

Normal Mode (real working environment)

Use Normal Mode when you want to test real authentication and backend behavior.

1. Add valid Firebase values in your .env file (see Environment Variables section above).
2. Launch the app with npx expo start.
3. Keep Demo Mode turned OFF on the login screen.
4. Sign in using valid real user credentials from your configured Firebase project.

Demo Mode vs Normal Mode

Area	Demo Mode	Normal Mode
Authentication	Simulated demo login	Real Firebase authentication
Credentials required	No backend setup needed	Valid .env Firebase config required
Password behavior	Any password accepted for demo accounts	Correct password required
Data source	Pre-populated mock/demo data	Live backend data
Best used for	UI walkthroughs, role previews, quick demos	Real workflow validation and production-like testing

📂 Project Structure Overview

citil-mobile/
├── App.js                 # Application entry point & Global Providers
├── app.json               # Expo configuration
├── src/
│   ├── components/        # Reusable UI components (Buttons, Cards, Inputs)
│   ├── config/            # Firebase and external service configurations
│   ├── context/           # React Contexts (AuthContext, AppContext)
│   ├── navigation/        # Drawer and Stack navigators
│   ├── screens/           # Role-based screens (Finance, Logistics, Staff, HOD)
│   ├── theme/             # Unified design system (colors, typography, spacing)
│   └── utils/             # Helper functions, Local DB wrapper, and API logic
└── assets/                # Local images, fonts, and screenshots

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.