forked from jamesp/sasa-membership
160 lines
7.9 KiB
Markdown
160 lines
7.9 KiB
Markdown
# Project Structure
|
|
|
|
```
|
|
membership/
|
|
├── .env # Local environment configuration
|
|
├── .env.example # Environment variable template
|
|
├── .gitignore # Git ignore rules
|
|
├── docker-compose.yml # Backend, frontend, gateway, and prod frontend services
|
|
├── restart.sh # Build, run fast tests, and restart the app
|
|
├── INSTRUCTIONS.md # Product requirements and roadmap context
|
|
├── README.md # Full project documentation
|
|
├── QUICKSTART.md # Short operator/developer guide
|
|
│
|
|
├── backend/ # FastAPI application
|
|
│ ├── Dockerfile
|
|
│ ├── requirements.txt
|
|
│ ├── alembic.ini
|
|
│ ├── alembic/ # Database migrations
|
|
│ └── app/
|
|
│ ├── main.py # App, CORS, health check, router registration
|
|
│ ├── api/
|
|
│ │ ├── dependencies.py # Auth dependencies
|
|
│ │ └── v1/
|
|
│ │ ├── auth.py # Register, login, password reset/change
|
|
│ │ ├── users.py # Users, profile questions, profile answers
|
|
│ │ ├── tiers.py # Membership tiers
|
|
│ │ ├── memberships.py
|
|
│ │ ├── payments.py # Manual, Square, refund, payment history
|
|
│ │ ├── email.py # SMTP2GO email tests and bounce webhooks
|
|
│ │ ├── email_templates.py
|
|
│ │ ├── events.py # Events and RSVPs
|
|
│ │ └── feature_flags.py
|
|
│ ├── core/ # Config, database, security, datetime helpers, default data
|
|
│ ├── models/ # SQLAlchemy models
|
|
│ ├── schemas/ # Pydantic schemas
|
|
│ ├── services/ # Email, bounce, Square, attendance, feature flags
|
|
│ └── tests/ # Fast backend pytest unit tests
|
|
│
|
|
├── docker/
|
|
│ └── gateway/ # Nginx dev gateway and self-signed TLS setup
|
|
│
|
|
└── frontend/ # React/Vite frontend
|
|
├── Dockerfile
|
|
├── package.json
|
|
├── vite.config.ts
|
|
└── src/
|
|
├── App.tsx # Routes, footer links, cookie notice
|
|
├── components/ # Dashboard, admin, payment, email, profile UI
|
|
├── contexts/ # Feature flag context/provider
|
|
├── pages/ # Login, register, dashboard, policy pages
|
|
├── services/ # API clients
|
|
└── utils/ # Shared frontend logic and Vitest tests
|
|
```
|
|
|
|
## Key Files
|
|
|
|
### Configuration
|
|
- **`.env`** - Runtime configuration for database, auth, Square, SMTP2GO, ports, and gateway TLS.
|
|
- **`docker-compose.yml`** - Services for FastAPI backend, Vite frontend, Nginx gateway, and production static frontend.
|
|
- **`restart.sh`** - Rebuilds images, runs frontend/backend unit tests, and restarts the stack only if tests pass.
|
|
|
|
### Backend Application
|
|
- **`backend/app/main.py`** - FastAPI app initialization, CORS, startup default-data seeding, routes, and health checks.
|
|
- **`backend/app/core/config.py`** - Settings management.
|
|
- **`backend/app/core/init_db.py`** - Default membership tiers, super admin, email templates, and profile questions.
|
|
- **`backend/app/core/security.py`** - JWT tokens and password hashing.
|
|
- **`backend/app/core/datetime.py`** - UTC helpers and Zulu serialization helpers.
|
|
- **`backend/app/models/models.py`** - Database tables.
|
|
- **`backend/app/schemas/schemas.py`** - API request/response models.
|
|
- **`backend/app/tests/test_profile_question_logic.py`** - Fast backend unit tests for profile answer validation.
|
|
- **`backend/app/tests/test_datetime_utc.py`** - UTC normalization and serialization tests.
|
|
|
|
### Frontend Application
|
|
- **`frontend/src/pages/Dashboard.tsx`** - Main member/admin dashboard.
|
|
- **`frontend/src/components/MembershipSetup.tsx`** - Membership tier selection and payment flow.
|
|
- **`frontend/src/components/SquarePayment.tsx`** - Square Web Payments SDK form.
|
|
- **`frontend/src/components/AdminProfileQuestionManager.tsx`** - Admin profile-question configuration.
|
|
- **`frontend/src/components/ProfileQuestionsForm.tsx`** - Member/admin answer form with dependency handling.
|
|
- **`frontend/src/components/EmailTemplateManagement.tsx`** - Email template editing.
|
|
- **`frontend/src/components/BounceManagement.tsx`** - SMTP2GO bounce management.
|
|
- **`frontend/src/components/EspReaderManagement.tsx`** - ESP reader, card, tap, and attendance admin UI.
|
|
- **`frontend/src/utils/profileQuestionLogic.test.ts`** - Fast frontend unit tests for profile-question visibility/editability.
|
|
- **`frontend/src/utils/timezone.ts`** - Europe/London display helpers and UTC conversion utilities.
|
|
|
|
## API Endpoints
|
|
|
|
- **`auth.py`** - Register, login, forgot password, reset password, change password.
|
|
- **`users.py`** - Current user profile, admin user CRUD, profile-question CRUD, member/admin profile answers, and role-guarded admin password reset emails.
|
|
- **`tiers.py`** - Membership tier CRUD.
|
|
- **`memberships.py`** - Member/admin membership management.
|
|
- **`payments.py`** - Payment history, manual payments, Square config/process/refund.
|
|
- **`events.py`** - Event CRUD, upcoming events, RSVP create/update, RSVP listing.
|
|
- **`email.py`** - SMTP2GO test emails, welcome email tests, bounce webhook, bounce stats, cleanup, deactivation.
|
|
- **`esp.py`** - ESP reader provisioning, time sync, tap capture, dashboard login, attendance, and queued write jobs.
|
|
- **`email_templates.py`** - Database-backed template listing, lookup, update, and default seeding.
|
|
- **`feature_flags.py`** - Public feature flag listing/lookup and super-admin-only reload.
|
|
|
|
## Database Models
|
|
|
|
Fully implemented:
|
|
- **User** - Authentication, profile, roles, volunteer level.
|
|
- **ProfileQuestion** - Configurable profile fields, options, dependencies, admin-only edit flags.
|
|
- **UserProfileAnswer** - Per-user answers with update attribution.
|
|
- **MembershipTier** - Configurable tiers with fees and benefits.
|
|
- **Membership** - User memberships with status, dates, and auto-renew flag.
|
|
- **Payment** - Payment records for Square, cash, check, and dummy methods.
|
|
- **Event** - Event management records.
|
|
- **EventRSVP** - RSVP and attendance records.
|
|
- **EmailTemplate** - Editable database-backed email templates.
|
|
- **EmailBounce** - SMTP2GO bounce, complaint, and unsubscribe tracking.
|
|
- **PasswordResetToken** - One-time password reset support.
|
|
- **EspReader** - Provisioned RFID readers with UTC heartbeat and time-sync data.
|
|
- **RfidTap** - UTC-normalized RFID tap records.
|
|
- **AttendanceSession** - Attendance sessions driven by RFID taps.
|
|
- **RfidCardWriteJob** - Queued RFID card write jobs.
|
|
- **VolunteerRole** - Volunteer role definitions.
|
|
- **VolunteerAssignment** - Member-to-role assignments.
|
|
- **VolunteerSchedule** - Volunteer shift schedules.
|
|
- **Certificate** - Training/certificate records.
|
|
- **File** - File repository metadata.
|
|
- **Notification** - Email notification logs.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Start everything
|
|
docker compose up -d
|
|
|
|
# View logs
|
|
docker compose logs -f
|
|
|
|
# Access API docs
|
|
# http://localhost:8050/docs
|
|
```
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
# Run both fast test suites and restart only if they pass
|
|
./restart.sh
|
|
|
|
# Run test suites individually
|
|
docker compose run --rm frontend npm test
|
|
docker compose run --rm backend pytest -q
|
|
```
|
|
|
|
## Default Credentials
|
|
|
|
**Admin**: admin@swanseaairport.org / admin123
|
|
|
|
**Database**: Configured via environment variables in `.env`.
|
|
|
|
## Remaining Roadmap
|
|
|
|
1. Expand authenticated API tests for member/admin workflows
|
|
2. Add member file repository endpoints and UI
|
|
3. Build richer volunteer assignment, schedule, and certificate screens
|
|
4. Add renewal reminder batch jobs
|
|
5. Add reporting and analytics
|