# Folder Structure

---

**Document Version:** 1.1
**Project:** Student Bazaar
**Document Type:** Project Folder Structure Specification
**Status:** Approved
**Last Updated:** 29 June 2026
**Author:** Nemmi Tangha

---

# 1. Purpose

This document defines the official folder structure for Student Bazaar.

The project follows a **Feature-Based Modular Architecture** using the Flask framework. Every feature is organized into its own module to improve maintainability, scalability, and code organization.

This folder structure serves as the standard for all development activities.

---

# 2. Project Structure

```text
Student Bazaar/
│
├── app/
│   │
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── services.py
│   │   ├── forms.py
│   │   ├── validators.py
│   │   └── utils.py
│   │
│   ├── marketplace/
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── services.py
│   │   ├── forms.py
│   │   ├── validators.py
│   │   └── utils.py
│   │
│   ├── negotiation/
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── services.py
│   │   ├── forms.py
│   │   ├── validators.py
│   │   └── utils.py
│   │
│   ├── chat/
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── services.py
│   │   ├── forms.py
│   │   ├── validators.py
│   │   └── utils.py
│   │
│   ├── meetup/
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── services.py
│   │   ├── forms.py
│   │   ├── validators.py
│   │   └── utils.py
│   │
│   ├── notifications/
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── services.py
│   │   ├── forms.py
│   │   ├── validators.py
│   │   └── utils.py
│   │
│   ├── admin/
│   │   ├── __init__.py
│   │   ├── routes.py
│   │   ├── services.py
│   │   ├── forms.py
│   │   ├── validators.py
│   │   └── utils.py
│   │
│   ├── models/
│   │   └── __init__.py
│   │
│   ├── shared/
│   │   ├── __init__.py
│   │   ├── decorators.py
│   │   ├── permissions.py
│   │   ├── helpers.py
│   │   ├── constants.py
│   │   └── exceptions.py
│   │
│   ├── static/
│   │   ├── css/
│   │   ├── js/
│   │   ├── images/
│   │   └── icons/
│   │
│   ├── templates/
│   │   ├── auth/
│   │   ├── marketplace/
│   │   ├── negotiation/
│   │   ├── chat/
│   │   ├── meetup/
│   │   ├── notifications/
│   │   ├── admin/
│   │   ├── shared/
│   │   └── layouts/
│   │
│   ├── config.py
│   ├── extensions.py
│   └── __init__.py
│
├── docs/
│
├── migrations/
│
├── tests/
│   ├── auth/
│   ├── marketplace/
│   ├── negotiation/
│   ├── chat/
│   ├── meetup/
│   ├── notifications/
│   └── admin/
│
├── uploads/
│   ├── profile_pictures/
│   ├── listing_images/
│   └── advertisements/
│
├── app.py
├── requirements.txt
├── README.md
├── CLAUDE.md
├── .env
└── .gitignore
```

---

# 3. Folder Responsibilities

## app/

Contains the complete Flask application, including feature modules, shared utilities, templates, static assets, and configuration.

---

## auth/

Responsible for:

* Registration
* Login
* Logout
* Email Verification
* Password Reset
* Profile Management

---

## marketplace/

Responsible for:

* Categories
* Product Listings
* Product Images
* Favorites
* Search & Filtering
* Listing Management

---

## negotiation/

Responsible for:

* Offers
* Counter Offers
* Offer Acceptance
* Offer Rejection
* Negotiation History

---

## chat/

Responsible for:

* Conversations
* Messages
* Chat Limits
* Rewarded Advertisement Unlocks
* Premium Messaging
* Contact Information Rules

---

## meetup/

Responsible for:

* Meet-up Scheduling
* Meet-up Confirmation
* Meet-up Completion
* Meet-up Cancellation

---

## notifications/

Responsible for:

* Notification Creation
* Notification Delivery
* Read Status
* User Alerts

---

## admin/

Responsible for:

* User Management
* Listing Moderation
* Reports
* Advertisement Management
* Premium Subscription Management
* System Settings
* Administrative Audit Logs
* Platform Analytics

---

## shared/

Contains reusable components shared across multiple modules.

Examples include:

* Custom Decorators
* Permission Checks
* Helper Functions
* Constants
* Custom Exceptions

---

# 4. Static Assets

The `static` directory contains all client-side resources.

Subdirectories include:

* CSS
* JavaScript
* Images
* Icons

Static assets should be organized by type and reused wherever possible.

---

# 5. Templates

Templates are organized by feature module.

Shared layouts are stored in:

```text
templates/layouts/
```

Reusable template components are stored in:

```text
templates/shared/
```

---

# 6. Uploads

User-uploaded files are stored outside the Flask application.

Directories include:

* Profile Pictures
* Listing Images
* Advertisement Images

All uploads must be validated before storage.

---

# 7. Database Migrations

The `migrations` directory stores Flask-Migrate migration files and maintains database schema history.

---

# 8. Testing

The `tests` directory mirrors the application modules.

Each feature should include unit and integration tests.

Example:

```text
tests/
├── auth/
├── marketplace/
├── negotiation/
├── chat/
└── admin/
```

---

# 9. Configuration Files

## app.py

Application entry point.

---

## config.py

Stores application configuration including:

* Database Configuration
* Mail Configuration
* Security Settings
* Upload Settings

---

## extensions.py

Initializes shared Flask extensions, including:

* SQLAlchemy
* Flask-Login
* Flask-Mail
* Flask-WTF (CSRF)
* Flask-Migrate

---

## .env

Stores sensitive configuration values such as:

* Secret Key
* Database Credentials
* Mail Credentials
* API Keys

The `.env` file must never be committed to version control.

---

## CLAUDE.md

Provides project-specific guidance for Claude Code, including:

* Architecture Rules
* Coding Standards
* Development Workflow
* Project Constraints

---

# 10. Naming Conventions

The project follows these conventions:

**Folders**

* lowercase
* meaningful feature names

**Files**

* snake_case

**Python Classes**

* PascalCase

**Functions**

* snake_case

**Constants**

* UPPER_CASE

**Variables**

* snake_case

---

# 11. Development Guidelines

Developers should:

* Keep feature modules independent.
* Place business logic inside service files.
* Keep routes lightweight.
* Reuse shared utilities.
* Avoid duplicated code.
* Follow Coding Standards.
* Write tests for new functionality.

---

# 12. Benefits

This folder structure provides:

* Clear separation of concerns
* Feature-based modularity
* Improved maintainability
* Better scalability
* Easier onboarding
* Consistent project organization
* Simplified testing

---

# 13. Conclusion

The Student Bazaar folder structure follows a modular Flask architecture built around independent feature modules. This structure supports clean code organization, maintainability, scalability, and consistent development practices. All implementation should conform to this structure unless an architectural revision is formally approved.