CampoSocial Server

CampoSocial Server is the Flask-based backend that powers the CampoSocial campus community platform. It exposes a feature-rich REST API layered on top of SQLAlchemy models, delivers real-time messaging through Flask-SocketIO, and ships with first-class, interactive documentation via Swagger UI and a bespoke API Explorer.

• Modular REST API at /camposocial/api covering authentication, users, events, marketplace, yaps, messaging, friends, badges, polls, groups, gamification, trending feeds, and notifications.
• Interactive documentation served by Flask-RESTX (/docs) plus a custom navigator (/api-explorer) that introspects the live routing table.
• JWT-based authentication with token blocklisting and one-day expirations.
• Real-time sockets for presence, message delivery, typing indicators, notifications, and yap counters, backed by Redis-friendly fan-out patterns.
• Object storage integration via boto3 for rich media uploads and CDN delivery.
• Comprehensive migrations and seeding scripts (migrations/, seed.py, seed_badges.py) to bootstrap environments.

camposocial-server/
├── app.py                # Flask application factory & Socket.IO bootstrap
├── models.py             # Core SQLAlchemy models
├── models_blocking.py    # Supplemental models (e.g., activity tracking)
├── views/                # Blueprinted REST resources grouped by domain
├── websocket_handlers.py # Socket.IO event handlers & presence logic
├── api_docs.py           # Swagger UI configuration and resource schemas
├── api_explorer.py       # Dynamic HTML explorer for routed endpoints
├── migrations/           # Alembic migration versions
├── requirements*.txt     # Production dependency locks
├── Pipfile               # Pipenv dependency manifest
├── docker-compose.yml    # App + Redis orchestration for local/dev
└── Dockerfile            # Gunicorn-based production image

• Python 3.13 (recommended) with Pipenv installed
• PostgreSQL 13+ (or another SQLAlchemy-supported database)
• Redis 7.x for WebSocket state fan-out
• (Optional) AWS-compatible object storage credentials for media uploads

Create an .env (or otherwise inject variables) with at least:

Additional feature-specific environment variables may be required depending on enabled integrations (see the relevant view modules for details).

pipenv install --dev
pipenv run flask --app app db upgrade    # apply database migrations
pipenv run python seed.py                # optional: seed baseline data
pipenv run python seed_badges.py         # optional: seed gamification badges
pipenv run python app.py                 # start Socket.IO-enabled dev server (defaults to :5001)

The server exposes REST endpoints on http://127.0.0.1:5001/camposocial/api/... and WebSocket connections at ws://127.0.0.1:5001/socket.io/ (supply auth: { token: "Bearer <JWT>" } during the initial handshake).

# Build & start the API and Redis locally (serves HTTP on :5000)
docker compose up --build

# Apply migrations from inside the container if needed
docker compose exec app flask --app app db upgrade

Ensure the required environment variables are exported or stored in a .env file so docker-compose can forward them to the container.

Use the built-in Alembic tooling via Flask-Migrate:

pipenv run flask --app app db migrate -m "describe your change"
pipenv run flask --app app db upgrade

Migrations live under migrations/versions/ and should be committed alongside schema changes.

• Swagger UI: Visit http://127.0.0.1:5001/docs to browse tagged endpoints, request/response models, and interact with live routes provided by api_docs.py.
• Custom Explorer: Visit http://127.0.0.1:5001/api-explorer for an interactive catalog that pulls directly from Flask's URL map. The explorer surfaces method filters, live search, auth indicators, and parameter hints generated by api_explorer.py.

Authenticating through Swagger UI requires clicking “Authorize” and pasting a valid Bearer <token> JWT. The explorer marks routes that likely require authentication and links back to the managing blueprint.

websocket_handlers.py powers Socket.IO events for:

• Connection authentication (token in the connect payload)
• Conversation room membership (join_conversation, leave_conversation)
• Typing indicators (typing, typing_indicator)
• Read receipts (message_read, messages_read)
• Notifications (friend_status_change, get_notification_counts, heartbeat acknowledgements)

Redis is recommended to scale the Socket.IO message bus when horizontally scaling the application.

• seed.py populates foundational users, events, and marketplace content.
• seed_badges.py primes the gamification tables.
• Additional migration helpers live in the repository root (e.g., migrate_conversation_fields.py). Review and run them as needed for data backfills.

pipenv run pytest

Individual tests are located in the repository root (test_*.py) and cover imports, live update flows, and MPesa integration.

• Production deployments typically run under Gunicorn (gunicorn app:app) as defined in the Dockerfile.
• Review fly.toml for Fly.io-specific configuration if targeting that platform.
• Ensure environment-specific secrets are injected securely and that migrations run before scaling up new instances.

For operational issues or feature requests, contact the CampoSocial maintainer team at support@camposocial.app or open an issue in the project tracker.