Wavve Backend

A social media platform exclusively for college students, verified through university email domains.

Vision

Wavve is a college-focused social network where students can:

• Share stories and connect with peers from their university
• Follow and interact with college organizations and clubs
• Discover and RSVP to campus events
• Share ideas and participate in discussions
• Build a verified college community

Current Phase: Authentication & University Verification (January 2026)

About

This backend API powers Wavve's authentication system. We're starting with a robust foundation that ensures only verified college students can access the platform.

Current Focus: Authentication

Building a secure authentication system with:

• University email verification via OTP
• Session management
• Multi-device support
• Role-based access

Future Vision (High Level)

Once authentication is complete, Wavve will expand to include:

• Social Features: User profiles, follow system, posts, stories, and feed
• Organizations: College clubs and organizations can create pages and manage content
• Events: Event creation, discovery, and RSVP system
• Discussions: Idea boards and threaded conversations

Details and specifications for future features will be designed and documented as we progress.

Tech Stack

• Framework: Phoenix 1.8 (Elixir)
• Database: PostgreSQL
• API Style: REST (JSON)
• Email: Swoosh
• Web Server: Bandit

Prerequisites

• Elixir 1.15+
• Erlang/OTP 26+
• PostgreSQL 14+

Quick Start

See docs/SETUP.md for detailed installation instructions.

# Quick start
git clone <repository-url>
cd wavve_backend
mix deps.get
./env_manager.sh switch dev
mix ecto.setup
mix phx.server

Server runs at http://localhost:4000

Development

Running Tests

mix test

Pre-commit Checks

mix precommit

Database Commands

# Create migration
mix ecto.gen.migration migration_name

# Run migrations
mix ecto.migrate

# Rollback
mix ecto.rollback

# Reset database
mix ecto.reset

Environment Switching

./env_manager.sh switch dev      # Development
./env_manager.sh switch staging  # Staging
./env_manager.sh switch prod     # Production

Current Database Schema

users

• Email, role, verification status
• Last login tracking

universities

• University name and status

university_domains

• Verified email domains (e.g., @stanford.edu)
• Domain types (student, alumni, faculty, org)

auth_providers

• OAuth provider connections (for future use)

otp_tokens

• Email verification codes
• Expiration and rate limiting

sessions

• Active user sessions
• Device tracking and management

Project Structure

lib/
├── wavve_backend/
│   ├── accounts/              # Authentication & users
│   │   ├── user.ex
│   │   ├── session.ex
│   │   ├── otp_token.ex
│   │   └── auth_provider.ex
│   ├── universities/          # University management
│   │   ├── university.ex
│   │   └── university_domain.ex
│   ├── application.ex
│   ├── repo.ex
│   └── mailer.ex
└── wavve_backend_web/
    ├── controllers/           # API endpoints
    ├── endpoint.ex
    └── router.ex

What Needs to Be Done

Phase 1: Authentication (Current - January 2026)

API Endpoints

• POST /api/auth/signup - Register with university email
• POST /api/auth/verify-email - Verify OTP code
• POST /api/auth/resend-otp - Resend verification code
• POST /api/auth/login - Email/password login
• POST /api/auth/logout - End session
• GET /api/auth/me - Current user info
• POST /api/auth/refresh - Refresh session

Business Logic

• User registration with university email validation
• OTP generation and email delivery
• Rate limiting for OTP requests
• Session management (create, validate, revoke)
• Password hashing with Bcrypt/Argon2
• JWT token generation and validation

Testing & Security

• Comprehensive test coverage
• Rate limiting middleware
• Brute force protection
• Input validation and sanitization

See docs/JANUARY_MILESTONE.md for detailed weekly breakdown.

Future Phases

Future features (user profiles, social graph, organizations, events, discussions) will be specified and designed after authentication is complete.

Contributing

We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation.

How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Implement your changes
4. Test thoroughly: mix test
5. Format code: mix format
6. Run precommit checks: mix precommit
7. Commit with clear messages
8. Push to your fork
9. Open a Pull Request

See docs/CONTRIBUTING.md for detailed guidelines.

Development Guidelines

• Follow Elixir and Phoenix conventions (see AGENTS.md)
• Write tests for new features
• Update documentation as needed
• Keep commits focused and atomic

Good First Issues

Look for issues tagged with good-first-issue:

• Email verification flow
• OTP validation logic
• Session management helpers
• API endpoint implementations
• Test coverage improvements

Configuration

Required Environment Variables

DATABASE_URL=ecto://postgres:postgres@localhost/wavve_backend_dev
SECRET_KEY_BASE=<generate with mix phx.gen.secret>
PHX_HOST=localhost

Optional Environment Variables

PORT=4000
POOL_SIZE=10
PHX_SERVER=true

See docs/ENVIRONMENT.md for complete configuration guide.

Documentation

All documentation is available in the docs/ folder:

• SETUP.md - Step-by-step installation guide
• ENVIRONMENT.md - Environment setup and configuration
• CONTRIBUTING.md - How to contribute
• JANUARY_MILESTONE.md - January 2026 tasks and weekly breakdown
• PROJECT_STATUS.md - Implementation status and roadmap
• API_RESPONSES.md - API response format and examples
• AGENTS.md - Code style and conventions (root level)

Roadmap

January 2026: Authentication & University Verification February 2026: User Profiles & Social Graph March 2026: Organizations & Events April 2026: Discussions & Content + Launch

Goal: Stable launch by end of April 2026

License

This project is licensed under the MIT License - see the LICENSE file for details.

Get Involved

• Issues: Report bugs or request features
• Discussions: Ask questions or share ideas
• Pull Requests: Contribute code or documentation

Built with ❤️ using Phoenix Framework and Elixir.