# tdk-bwcb/campus-lost-found-market architecture

> Architecture diagram of the GitHub repository tdk-bwcb/campus-lost-found-market, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tdk-bwcb/campus-lost-found-market
- Repository: https://github.com/tdk-bwcb/campus-lost-found-market

## Overview

##### Project Type and Purpose
- This is a full-stack Flask web application ("Campus Hub") that provides two main user-facing features:
- Lost & Found item submission/tracking
- Peer-to-peer Marketplace listings (buy/sell/trade)
- Key characteristics from README and file tree:
- Python/Flask backend with Jinja2 templates
- SQLite for persistent storage
- Flask-Login/Flask-Session for authentication & sessions
- Flask-Mail (Gmail SMTP) for email verification/alerts
- Blueprint-based modular routing (auth, lost_and_found, marketplace)

##### File Structure Analysis
- Top-level application entry: Main.py
- extensions.py and models.py initialize and register core services (DB, mail, login, session)
- blueprints/…: three distinct route modules (auth, lost_and_found, marketplace)
- static/ & templates/: front-end assets and view templates (organized per blueprint)
- flask_session/: server-side session store (file system backend)
- reset_db.py: utility to bootstrap/reset the SQLite schema

##### Core Components
a. Frontend (Client)
- Browser → HTTP(S) requests
b. Web Server Layer
- (Optional) Nginx/Apache reverse proxy or Flask built-in dev server
c. Flask Application
- Application Factory (Main.py + extensions.py)
- Blueprint Modules:
– Auth Blueprint (routes: register, login, profile)
– Lost & Found Blueprint (dashboard, report, detail, edit)
– Marketplace Blueprint (dashboard, create, detail, edit)
- Template Engine (Jinja2) renders UI with static assets (Tailwind-ready)
d. Business Logic & Persistence
- models.py: ORM-like definitions interacting with SQLite DB
- Flask-Login + Flask-Session: session & user state management (filesystem store)
e. External Services
- Gmail SMTP (Flask-Mail) for email verification & alerts

##### Interactions & Data Flows
- Client ↔ Web Server: HTTP(S) requests/responses
- Web Server → Flask App: routes mapped via blueprints
- Flask App → SQLite DB: CRUD operations via models.py
- Flask App → SMTP Server: transactional emails (registration, notifications)
- Flask App ↔ Session Store (flask_session folder): session read/write
- Flask App renders templates, serves static files

##### Architectural Patterns & Design Principles
- MVC (Model–View–Controller) separation:
- Controllers = Flask blueprints
- Models = models.py + SQLite
- Views = Jinja2 templates + static assets
- Modularization by feature (three blueprints)
- Explicit application factory pattern (central init in Main.py/extensions.py)
- Single-schema SQLite for simplicity (monolithic persistence)

- Clear component labels: Browser, Nginx/Flask Server, Flask Application (with sub-components), SQLite DB, SMTP Service
- Green = User/Client
- Blue = Application core (blueprints & extensions)
- Orange = Data stores (DB, session files)
- Purple = External services (SMTP)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    Browser["Browser"]:::client

    %% Server Layer
    Server["Nginx/Flask Server"]:::server

    Browser -->|"HTTP(S) GET/POST"| Server

    %% Application Core
    subgraph "Flask Application"
        direction TB
        Factory["Main.py (App Factory)"]:::app
        Extensions["extensions.py"]:::app
        Models["models.py"]:::app
        ResetDB["reset_db.py (DB Reset Utility)"]:::utility

        subgraph "Auth Blueprint"
            direction TB
            AuthInit["__init__.py"]:::blueprint
            AuthRoutes["routes.py"]:::blueprint
            AuthTemplates["templates/auth/*"]:::template
        end

        subgraph "Lost & Found Blueprint"
            direction TB
            LfInit["__init__.py"]:::blueprint
            LfRoutes["routes.py"]:::blueprint
            LfTemplates["templates/lost_and_found/*"]:::template
        end

        subgraph "Marketplace Blueprint"
            direction TB
            MpInit["__init__.py"]:::blueprint
            MpRoutes["routes.py"]:::blueprint
            MpTemplates["templates/marketplace/*"]:::template
        end

        GlobalTemplates["templates/base.html, 404.html, 500.html"]:::template
        StaticAssets["static/*"]:::static
    end

    Server -->|"WSGI Call"| Factory

    Factory --> Extensions
    Factory --> Models
    Factory --> ResetDB

    Factory --> AuthInit
    AuthInit --> AuthRoutes
    AuthRoutes --> AuthTemplates

    Factory --> LfInit
    LfInit --> LfRoutes
    LfRoutes --> LfTemplates

    Factory --> MpInit
    MpInit --> MpRoutes
    MpRoutes --> MpTemplates

    Factory --> GlobalTemplates
    Factory --> StaticAssets

    %% Data Stores & External Services
    DB[(SQLite Database)]:::database
    SessionStore[/"flask_session/"/]:::database
    SMTPService[("Gmail SMTP Service")]:::external

    Factory -->|"SQL CRUD"| DB
    Factory -->|"Session R/W"| SessionStore
    Factory -->|"SMTP Email"| SMTPService

    %% Click Events
    click Factory "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/Main.py"
    click Extensions "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/extensions.py"
    click Models "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/models.py"
    click ResetDB "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/reset_db.py"
    click AuthInit "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/blueprints/auth/__init__.py"
    click AuthRoutes "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/blueprints/auth/routes.py"
    click AuthTemplates "https://github.com/tdk-bwcb/campus-lost-found-market/tree/main/templates/auth/"
    click LfInit "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/blueprints/lost_and_found/__init__.py"
    click LfRoutes "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/blueprints/lost_and_found/routes.py"
    click LfTemplates "https://github.com/tdk-bwcb/campus-lost-found-market/tree/main/templates/lost_and_found/"
    click MpInit "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/blueprints/marketplace/__init__.py"
    click MpRoutes "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/blueprints/marketplace/routes.py"
    click MpTemplates "https://github.com/tdk-bwcb/campus-lost-found-market/tree/main/templates/marketplace/"
    click GlobalTemplates "https://github.com/tdk-bwcb/campus-lost-found-market/blob/main/templates/base.html"
    click StaticAssets "https://github.com/tdk-bwcb/campus-lost-found-market/tree/main/static/"

    %% Styles
    classDef client fill:#8FBC8F,stroke:#333,stroke-width:1px
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#E0FFFF,stroke:#333,stroke-width:1px
    classDef blueprint fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef template fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef static fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef database fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef utility fill:#EEE8AA,stroke:#333,stroke-width:1px
```
