Skip to content

Commit 8493391

Browse files
kunaljit3006kunaljit3006
authored
Add README for Campus Safety App
Added detailed information about the Campus Safety App, including features, tech stack, project structure, installation instructions, usage guidelines, and development guidelines.
1 parent 8c66113 commit 8493391

1 file changed

Lines changed: 301 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
# Campus Safety App
2+
3+
A mobile application designed to enhance campus safety by allowing users to report bugs and safety concerns directly from their Android devices. Built with Kotlin and modern Android development practices.
4+
5+
## 📱 Overview
6+
7+
The Campus Safety App is an Android application that streamlines the bug reporting process for campus communities. Users can easily describe issues, attach screenshots, and send reports directly to the development team via email integration.
8+
9+
## ✨ Features
10+
11+
- **Bug Reporting**: Simple and intuitive interface to report bugs and issues
12+
- **Screenshot Attachment**: Attach images/screenshots to bug reports for better documentation
13+
- **Email Integration**: Send reports directly to the development team using Gmail
14+
- **File Management**: Browse and select files from device storage
15+
- **Confirmation Screen**: Dedicated "Done" activity confirming successful report submission
16+
- **Material Design**: Modern UI following Material Design guidelines
17+
- **Edge-to-Edge UI**: Full-screen modern Android experience with system insets handling
18+
19+
## 🛠️ Tech Stack
20+
21+
- **Language**: Kotlin
22+
- **Min SDK**: Android 7.0 (API 24)
23+
- **Target SDK**: Android 14 (API 34)
24+
- **Compile SDK**: Android 15 (API 35)
25+
- **Build System**: Gradle with Kotlin DSL
26+
27+
### Dependencies
28+
29+
- **AndroidX**:
30+
- `androidx.core:core-ktx` - Kotlin extensions for Android core library
31+
- `androidx.appcompat:appcompat` - Backward compatibility for AppCompat features
32+
- `androidx.activity` - Activity component
33+
- `androidx.constraintlayout` - Constraint layout for flexible UI design
34+
35+
- **Material Design**:
36+
- `material:material` - Material Design components
37+
38+
- **Testing**:
39+
- JUnit - Unit testing framework
40+
- AndroidX Test - Instrumented testing
41+
42+
## 📂 Project Structure
43+
44+
```
45+
Campus-Safety-App/
46+
├── app/
47+
│ ├── src/
48+
│ │ ├── main/
49+
│ │ │ ├── java/com/example/campussafetyapp/
50+
│ │ │ │ ├── MainActivity.kt # Main activity entry point
51+
│ │ │ │ ├── BugActivity.kt # Bug reporting screen
52+
│ │ │ │ └── DoneActivity.kt # Confirmation screen
53+
│ │ │ ├── res/
54+
│ │ │ │ ├── layout/ # XML layout files
55+
│ │ │ │ ├── drawable/ # Drawable resources
56+
│ │ │ │ └── xml/ # Backup and extraction rules
57+
│ │ │ └── AndroidManifest.xml # App configuration
58+
│ │ ├── androidTest/ # Instrumented tests
59+
│ │ └── test/ # Unit tests
60+
│ ├── build.gradle.kts # App-level build configuration
61+
│ ├── google-services.json # Firebase configuration (if applicable)
62+
│ └── proguard-rules.pro # ProGuard configuration
63+
├── gradle/
64+
│ └── libs.versions.toml # Centralized dependency versions
65+
├── build.gradle.kts # Project-level build configuration
66+
├── settings.gradle.kts # Gradle settings
67+
├── gradle.properties # Gradle properties
68+
└── README.md # This file
69+
```
70+
71+
## 🎯 Main Components
72+
73+
### MainActivity
74+
Entry point of the application that initializes the main UI with edge-to-edge display support.
75+
76+
**Features**:
77+
- Enables edge-to-edge display
78+
- Handles system insets (status bar, navigation bar)
79+
- Sets up the main layout
80+
81+
### BugActivity
82+
The core activity for reporting bugs with attachment capabilities.
83+
84+
**Features**:
85+
- Bug description text input
86+
- Image attachment picker
87+
- File attachment display with filename
88+
- Email intent integration with Gmail
89+
- Toast notifications for user feedback
90+
- File URI permission handling
91+
92+
**Key Methods**:
93+
- `onCreate()`: Initializes UI bindings and sets up click listeners
94+
- `pickImage()`: Handles image selection from device storage
95+
- `sendBugBtn`: Validates input and launches email intent
96+
- `onResume()`: Handles post-email navigation to DoneActivity
97+
98+
### DoneActivity
99+
Confirmation screen displayed after successfully sending a bug report.
100+
101+
**Features**:
102+
- Confirmation message display
103+
- Back button navigation
104+
- System back button handling
105+
- Returns user to BugActivity
106+
107+
## 🔧 Installation & Setup
108+
109+
### Prerequisites
110+
- Android Studio (latest version recommended)
111+
- JDK 1.8 or higher
112+
- Android SDK 24 (API 24) or higher
113+
- Gmail app installed on testing device (for email functionality)
114+
115+
### Clone the Repository
116+
117+
```bash
118+
git clone https://github.com/gdsc-nits-org/Campus-Safety-App.git
119+
cd Campus-Safety-App
120+
```
121+
122+
### Build the Project
123+
124+
1. **Using Android Studio**:
125+
- Open the project in Android Studio
126+
- Android Studio will automatically download required dependencies
127+
- Click "Build" > "Make Project"
128+
129+
2. **Using Command Line**:
130+
```bash
131+
./gradlew clean build
132+
```
133+
134+
### Run the Application
135+
136+
1. **Using Android Studio**:
137+
- Connect an Android device or launch an emulator
138+
- Click "Run" > "Run 'app'"
139+
140+
2. **Using Command Line**:
141+
```bash
142+
./gradlew installDebug
143+
```
144+
145+
## 🚀 Usage
146+
147+
### Reporting a Bug
148+
149+
1. **Launch the App**: Open the Campus Safety App from your device
150+
2. **Describe the Issue**: Type your bug description in the text field
151+
3. **Attach Evidence** (Optional):
152+
- Tap the "Choose File" button
153+
- Select an image/screenshot from your device
154+
4. **Send Report**:
155+
- Tap the "Send" button
156+
- Gmail will open with the bug report pre-filled
157+
- Review and send the email
158+
5. **Confirmation**: The app shows a confirmation screen after sending
159+
160+
### Email Configuration
161+
162+
Reports are sent to: `kkunaljit@gmail.com`
163+
164+
To change the recipient email, modify the `EXTRA_EMAIL` parameter in `BugActivity.kt`:
165+
166+
```kotlin
167+
putExtra(Intent.EXTRA_EMAIL, arrayOf("your-email@example.com"))
168+
```
169+
170+
## 🔐 Permissions
171+
172+
The app requires the following permissions (declared in `AndroidManifest.xml`):
173+
174+
- `android.permission.INTERNET` - For email functionality
175+
176+
Additional implicit permissions:
177+
- Reading external storage (for file selection)
178+
- Gmail app package access (for email client integration)
179+
180+
## 🎨 UI/UX
181+
182+
### Design Features
183+
- Material Design 3 compliance
184+
- Edge-to-edge display with inset handling
185+
- Responsive layouts using ConstraintLayout
186+
- Custom drawables for visual elements
187+
- Smooth activity transitions
188+
189+
### Layout Files
190+
- `activity_main.xml` - Main activity layout
191+
- `activity_bug.xml` - Bug reporting form layout
192+
- `activity_done.xml` - Confirmation screen layout
193+
194+
## 📦 Build Configuration
195+
196+
### Gradle Configuration
197+
- **Build Tools Version**: 35
198+
- **Compile SDK**: 35
199+
- **Min SDK**: 24 (Android 7.0)
200+
- **Target SDK**: 34 (Android 14)
201+
202+
### Version Information
203+
- **Current Version**: 1.0
204+
- **Version Code**: 1
205+
206+
## 🧪 Testing
207+
208+
The project includes test configurations:
209+
210+
```bash
211+
# Run unit tests
212+
./gradlew test
213+
214+
# Run instrumented tests
215+
./gradlew connectedAndroidTest
216+
```
217+
218+
Test files are located in:
219+
- `app/src/test/java/` - Unit tests
220+
- `app/src/androidTest/java/` - Instrumented tests
221+
222+
## 🐛 Troubleshooting
223+
224+
### Gmail App Not Found
225+
- Ensure Gmail is installed on your testing device
226+
- The app requires Gmail for email functionality
227+
- Without Gmail, users will see a toast message: "Gmail app not found!"
228+
229+
### File Selection Issues
230+
- Grant file access permissions when prompted
231+
- Ensure the selected image file is valid and accessible
232+
- Check content resolver for proper URI handling
233+
234+
### Activity Navigation Issues
235+
- The app uses Intent flags to properly manage back stack
236+
- Use the provided back buttons for consistent navigation
237+
238+
## 🔄 Project Status
239+
240+
- **Status**: Active Development
241+
- **Latest Version**: 1.0
242+
- **Last Updated**: 2026
243+
- **Organization**: GDSC NITS (Google Developer Student Clubs - NIT Silchar)
244+
245+
## 📝 Development Guidelines
246+
247+
### Code Style
248+
- Kotlin best practices
249+
- ViewBinding for type-safe view access
250+
- Activity-based architecture
251+
- Material Design principles
252+
253+
### Adding New Features
254+
1. Create new Activity classes extending `AppCompatActivity`
255+
2. Use ViewBinding for layout references
256+
3. Implement edge-to-edge display support
257+
4. Handle system insets properly
258+
5. Add appropriate intent-filters in `AndroidManifest.xml`
259+
260+
## 🤝 Contributing
261+
262+
Contributions are welcome! To contribute:
263+
264+
1. Fork the repository
265+
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
266+
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
267+
4. Push to the branch (`git push origin feature/AmazingFeature`)
268+
5. Open a Pull Request
269+
270+
## 📋 Future Enhancements
271+
272+
Potential features for future releases:
273+
- Multiple recipient emails for bug reports
274+
- Category selection for bug types
275+
- Priority levels for bug severity
276+
- Database integration for offline storage
277+
- Analytics integration for crash reporting
278+
- User authentication and account management
279+
- Push notifications for bug report status
280+
- Camera integration for real-time screenshots
281+
- Attachment file size validation
282+
283+
## 📄 License
284+
285+
This project is maintained by GDSC NITS. For license information, please contact the organization.
286+
287+
## 📞 Support & Contact
288+
289+
- **Organization**: Google Developer Student Clubs - NIT Silchar
290+
- **Repository**: [gdsc-nits-org/Campus-Safety-App](https://github.com/gdsc-nits-org/Campus-Safety-App)
291+
- **Bug Reports**: Use the app itself to report issues!
292+
293+
## 🙏 Acknowledgments
294+
295+
- **Developer**: Kunal Jit (contact: kkunaljit@gmail.com)
296+
- **Organization**: GDSC NITS
297+
- **Frameworks**: Google's Material Design, AndroidX libraries
298+
299+
---
300+
301+
**Made with ❤️ by GDSC NITS for Campus Safety**

0 commit comments

Comments
 (0)