Neighborly Notes

A neighborhood notes club application where users create profiles, meet each other, and keep personal notes.

Features

• User Authentication: JWT-based auth with access/refresh tokens
• Password Reset: Recovery via personal codeword system
• User Profiles: Public profiles with avatar file upload and bio
• File Upload: Upload profile pictures with automatic resizing and optimization
• Secret Notebook: Personal notes visible only to owner (and admin)
• Admin Dashboard: Full administrative control for the "Caretaker"

Tech Stack

• Frontend: Vue 3 + TypeScript + Vite + Tailwind CSS + Pinia + Vue Router
• Backend: Python 3.12 + Flask + SQLAlchemy + Alembic + Pydantic + Gunicorn
• Database: PostgreSQL 15
• Deployment: Docker + docker-compose

Quick Start

1. Copy environment variables:

   cp .env.example .env

2. Start the application:

   docker compose up --build

3. Access the application:

   • Frontend: http://localhost:8080
   • Backend API: http://localhost:8000
   • PgAdmin: http://localhost:5050 (admin@example.com / admin)

Test Accounts

⚠️ Security Note: Demo credentials are not displayed on the login page for security reasons.

• Admin: caretaker / caretaker123 (codeword: lantern)
• Users: alice / alice123 (codeword: wonderland)
• Users: bob / bob123 (codeword: builder)

For Production: Use the admin creation script to create your first admin user securely.

File Upload

The application supports avatar file uploads with the following features:

• Supported Formats: JPG, PNG, GIF, WebP
• File Size Limit: 5MB maximum
• Automatic Processing: Images are automatically resized to 300x300px and optimized
• Persistent Storage: Files are stored in Docker volumes for persistence across container restarts

Avatar Upload API

• POST /api/uploads/avatar - Upload new avatar (multipart/form-data)
• DELETE /api/uploads/avatar - Remove current avatar
• GET /api/uploads/avatar/info - Get avatar information
• GET /api/uploads/avatars/{filename} - Serve avatar images

Production Deployment

Security Configuration

1. Set Production Environment:

   FLASK_ENV=production
   FLASK_DEBUG=false

2. Create Secure Admin User:

   # In production, use the secure admin creation script
   docker compose exec backend python create_admin.py
   
   # Or if running locally:
   cd backend && python create_admin.py

3. Update Security Settings:

   • Change JWT_SECRET to a strong, random 32+ character key
   • Use strong database passwords
   • Update CORS_ORIGINS to match your domain
   • Review all environment variables

Production Checklist

• Set FLASK_ENV=production
• Generate secure JWT_SECRET
• Create admin user with create_admin.py
• Update database credentials
• Configure CORS for your domain
• Set up SSL/HTTPS
• Review security headers
• Set up proper logging
• Configure database backups

Environment Variables

Backend (.env or backend/.env)

DATABASE_URL=postgresql+psycopg2://neighborly:neighborly123@db:5432/neighborlydb
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
JWT_REFRESH_TOKEN_EXPIRE_DAYS=7
FLASK_ENV=development

Database (docker-compose.yml)

POSTGRES_USER=neighborly
POSTGRES_PASSWORD=neighborly123
POSTGRES_DB=neighborlydb

PgAdmin (docker-compose.yml)

PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=admin

API Documentation

Base URL: http://localhost:8000/api

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• POST /api/auth/refresh - Refresh access token
• POST /api/auth/logout - Logout user
• POST /api/auth/reset/init - Initialize password reset
• POST /api/auth/reset/complete - Complete password reset

Profile

• GET /api/profile/me - Get own profile
• PATCH /api/profile/me - Update own profile
• GET /api/profile/:username - View user profile
• GET /api/users - List all users

Notes

• GET /api/notes/me - Get own notes
• POST /api/notes - Create note
• PATCH /api/notes/:id - Update note
• DELETE /api/notes/:id - Delete note

Admin

• GET /api/admin/users - List all users (admin)
• GET /api/admin/users/:username - Get user details (admin)
• PATCH /api/admin/users/:username/password - Change user password (admin)
• DELETE /api/admin/users/:username - Delete user (admin)
• GET /api/admin/users/:username/notes - Get user notes (admin)

SBOM Generation

The application generates Software Bill of Materials (SBOM) files in CycloneDX format during the Docker build process:

# Build and generate SBOM files
docker compose build

# Extract SBOM files from built images
make sbom

SBOM artifacts will be available in ./sbom/:

• frontend.cyclonedx.json - Frontend dependencies
• backend.cyclonedx.json - Backend dependencies

Development

Backend Development

cd backend
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
export FLASK_APP=app.main:app
flask db upgrade
python seed.py
flask run --port 8000

Frontend Development

cd frontend
npm install
npm run dev

Project Structure

neighborly-notes/
├── README.md
├── .env.example
├── docker-compose.yml
├── Makefile
├── frontend/
│   ├── Dockerfile
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── src/
│       ├── main.ts
│       ├── router/
│       ├── stores/
│       ├── pages/
│       ├── components/
│       └── lib/
└── backend/
    ├── Dockerfile
    ├── requirements.txt
    ├── app/
    │   ├── main.py
    │   ├── config.py
    │   ├── models.py
    │   ├── schemas.py
    │   ├── auth/
    │   ├── profiles/
    │   ├── notes/
    │   ├── admin/
    │   └── utils/
    ├── migrations/
    └── seed.py