Nexus

��# Nexus - Club & Team Management Application

Status: =ا� Phase 1 Foundation Complete | <د� Ready for Firebase Configuration

A modern, mobile-first club and team management application built with React, TypeScript, and Firebase.

---

<؉� What's Been Built (Phase 1)

' Project Foundation

• Vite + React 18 + TypeScript - Modern build tooling
• Tailwind CSS - Utility-first styling with custom design system
• React Router v6 - Client-side routing
• TanStack Query - Data fetching & caching
• Firebase SDK v10 - Backend integration (config needed)

' TypeScript Types

• Complete type definitions from database schema (src/types/index.ts)
• All 20+ Firestore collections typed
• User, Club, Team, Event, Chat, Subscription types and more

' Authentication System

• AuthContext - User state management
• Login page (/login)
• Register page (/register)
• Email verification workflow
• Firebase Auth integration ready

' Responsive Layout System

• Container component - Smart responsive widths
• AppLayout - Top navigation + content area
• Mobile-first design (375px �! 2560px+)
• Content max 1200px on desktop, 60% viewport on ultrawide

' Design System

• Colors: Royal Blue (#4169E1), Orange (#FF8C00), White
• Typography: Fluid scaling, max 75 chars/line
• Components: Ready for Button, Card, Modal, etc.
• Breakpoints: xs, sm, md, lg, xl, 2xl, 3xl

' Configuration Files

• src/config/firebase.ts - Firebase initialization (�&� needs your config)
• src/config/brand.ts - Brand colors, breakpoints, typography
• .cursorrules - AI assistant guidelines
• Tailwind, PostCSS, ESLint configs

---

=؀� Next Steps: Firebase Setup

Step 1: Create Firebase Project

1. Go to https://console.firebase.google.com/
2. Click "Add Project"
3. Name: nexus (or your preferred name)
4. Enable Google Analytics (optional)
5. Create project

Step 2: Enable Firebase Services

Authentication

1. Go to Authentication �! Get Started
2. Enable Email/Password sign-in method
3. (Optional) Enable Google sign-in

Firestore Database

1. Go to Firestore Database �! Create Database
2. Start in Test Mode (we'll add rules later)
3. Choose your region (closest to you)
4. Click Enable

Storage (Optional)

1. Go to Storage �! Get Started
2. Start in Test Mode
3. Click Done

Step 3: Get Firebase Config

1. Go to Project Settings (gear icon) �! General
2. Scroll to Your apps section
3. Click Web icon (</>) to add web app
4. Register app: Name it "Nexus Web"
5. Copy the firebaseConfig object

It looks like this:

const firebaseConfig = {
  apiKey: "AIzaSyC...",
  authDomain: "your-project.firebaseapp.com",
  projectId: "your-project-id",
  storageBucket: "your-project.appspot.com",
  messagingSenderId: "123456789",
  appId: "1:123456789:web:abc123",
  measurementId: "G-XXXXXXXXXX"
};

Step 4: Update Firebase Config

Open src/config/firebase.ts and replace the placeholder config:

// REPLACE THIS:
const firebaseConfig = {
  apiKey: "YOUR_API_KEY_HERE",
  authDomain: "YOUR_PROJECT.firebaseapp.com",
  // ...
};

// WITH YOUR ACTUAL CONFIG FROM FIREBASE CONSOLE
const firebaseConfig = {
  apiKey: "AIzaSyC...",
  authDomain: "nexus-abc123.firebaseapp.com",
  // ... (paste your actual values)
};

---

=ػ� Running the Application

Development Server

npm run dev

Opens at: http://localhost:5173

Build for Production

npm run build

Preview Production Build

npm run preview

---

=��� Project Structure

nexus/
%%% src/
%   %%% components/
%   %   %%% layout/
%   %       %%% Container.tsx      # Responsive container
%   %       %%% AppLayout.tsx      # Main layout with nav
%   %%% pages/
%   %   %%% auth/
%   %   %   %%% Login.tsx          # Login page
%   %   %   %%% Register.tsx       # Registration page
%   %   %%% Dashboard.tsx          # Main dashboard
%   %%% contexts/
%   %   %%% AuthContext.tsx        # Authentication state
%   %%% types/
%   %   %%% index.ts               # TypeScript types
%   %%% config/
%   %   %%% firebase.ts            # �&� UPDATE THIS
%   %   %%% brand.ts               # Brand config
%   %%% App.tsx                    # Main app component
%   %%% main.tsx                   # Entry point
%   %%% index.css                  # Global styles
%%% public/                        # Static assets
%%% .cursorrules                   # AI assistant rules
%%% package.json
%%% tsconfig.json
%%% tailwind.config.js
%%% vite.config.ts

---

<ب� Design System

Colors

// Primary (Royal Blue)
bg-primary         // #4169E1
text-primary

// Accent (Orange)
bg-accent         // #FF8C00
text-accent

// Semantic
bg-success        // Green
bg-warning        // Amber
bg-error          // Red

Responsive Breakpoints

xs: '375px'   // Mobile small
sm: '640px'   // Mobile large
md: '768px'   // Tablet
lg: '1024px'  // Desktop
xl: '1280px'  // Large desktop
2xl: '1536px' // Ultrawide
3xl: '2560px' // 4K ultrawide

Typography

text-fluid-sm    // Scales 0.875rem �! 1rem
text-fluid-base  // Scales 1rem �! 1.125rem
text-fluid-lg    // Scales 1.125rem �! 1.5rem

---

=��� Documentation Reference

All features documented in: C:\Users\kicka\Documents\MyApps\Nexus\nexus-app\docs\

Key Documents

Document	Purpose
00-project-structure.md	File organization, dependencies
01-user-management.md	User roles, permissions, auth flow
02-database-schema.md	Firestore collections, types
03-calendar-system.md	Events, RSVP, lock periods
08-business-rules.md	Validation, workflows, constraints
13-design-system.md	UI/UX, components, responsive design

Master Index: docs/README.md

---

=�� User Roles

Role	Level	Description
admin	5	Platform super admin
clubOwner	4	Owns clubs, manages teams
trainer	3	Manages teams, creates events
assistant	2	Helps trainers
user	1	Regular member
parent	1	Manages child subaccounts

See docs/01-user-management.md for permission matrix.

---

=���� Roadmap

' Phase 1: Foundation (COMPLETE)

• Project setup
• TypeScript types
• Authentication pages
• Responsive layout
• Design system

<د� Phase 2: User Management (NEXT)

• User role system
• Permission hooks
• Profile views
• Role-based navigation
• User management UI

=��� Phase 3: Clubs & Teams

• Club creation
• Team management
• Member management
• Join requests

=��� Phase 4: Calendar System

• Calendar views (month/week/day)
• Event creation
• RSVP system
• Lock periods

=��� Phase 5+: Advanced Features

• Statistics & leaderboards
• Push notifications
• Chat system
• Attendance tracking
• League schedule scraper

---

=���� Development Guidelines

Code Style

• ' TypeScript for everything
• ' Functional components with hooks
• ' TanStack Query for data fetching
• ' Proper error handling & loading states
• ' Mobile-first responsive design

Before Implementing Features

1. Read documentation (docs/ folder)
2. Check database schema (docs/02-database-schema.md)
3. Review business rules (docs/08-business-rules.md)
4. Follow design system (docs/13-design-system.md)

File Organization

• components/common/ - Reusable UI (Button, Card, Modal)
• components/layout/ - Layout components (Container, AppLayout)
• components/features/ - Feature-specific components
• pages/ - Route pages
• hooks/ - Custom hooks
• services/firebase/ - Firebase operations (split by collection)

---

=ب� Important Notes

�&� Firebase Config Required

The app will not work until you:

1. Create a Firebase project
2. Enable Authentication & Firestore
3. Update src/config/firebase.ts with your config

=�� Security Rules

When ready, deploy Firestore security rules:

1. Copy rules from docs/10-security-rules.md
2. Adapt to your needs
3. Deploy: firebase deploy --only firestore:rules

=��� Mobile-First

Always design for mobile (375px) first, then enhance for larger screens.

<ب� Design Consistency

Use Tailwind classes from the design system. Avoid arbitrary values.

---

=��� Support & Resources

Documentation

• Project Docs: C:\Users\kicka\Documents\MyApps\Nexus\nexus-app\docs\
• Cursor Rules: .cursorrules in project root

External Resources

• Firebase Documentation
• React Documentation
• Tailwind CSS
• TanStack Query

---

<د� Success Criteria

Phase 1 Complete When:

• Project builds without errors
• Firebase config structure ready
• TypeScript types defined
• Auth pages functional (once Firebase configured)
• Responsive layout works
• Design system implemented

Next Phase 2 Complete When:

• User roles implemented
• Permission system working
• Profile management functional
• Role-based UI rendering

---

=؀� Quick Start Checklist

• Create Firebase project
• Enable Authentication (Email/Password)
• Enable Firestore Database
• Copy Firebase config
• Update src/config/firebase.ts
• Run npm run dev
• Test registration at /register
• Test login at /login
• View dashboard at /

---

Built with d'� by following comprehensive documentation
Version: 1.0.0-alpha
Last Updated: January 15, 2026

---

<؉� You're Ready!

Once you update the Firebase config, you can:

1. Start the dev server: npm run dev
2. Register a new account
3. Start building Phase 2 features

Happy coding! =؀�