Project Structure Overview

Project Structure Overview

This document provides a comprehensive overview of the 8531 TeamSite project structure, explaining the purpose and organization of each directory and key file.

📁 Directory Structure

/srv/team.8531.ca/
├── .dev/                           # Development documentation
│   └── 1. domain-auth-strategy.md   # Domain authentication strategy
├── .env.example                    # Environment variables template
├── .git/                           # Git version control
├── .gitignore                      # Git ignore patterns
├── astro.config.mjs                # Astro configuration file
├── node_modules/                   # Installed dependencies
├── package.json                    # Project dependencies and scripts
├── package-lock.json               # Locked dependency versions
├── public/                         # Static assets
│   ├── favicon.svg                 # Site favicon
│   └── robots.txt                  # Search engine instructions
├── src/                            # Source code
│   ├── components/                 # Reusable Astro components
│   │   ├── AuthButton.astro       # Login/logout button component
│   │   └── GoogleDriveFolder.astro # Google Drive folder display component
│   ├── content/                    # Content collections
│   │   ├── config.ts              # Content schema and collection configuration
│   │   └── docs/                   # Documentation pages
│   │       ├── index.md            # Homepage documentation
│   │       ├── public/            # Publicly accessible content
│   │       │   ├── About/         # General information pages
│   │       │   ├── Policies/      # Public policy documents
│   │       │   ├── Test1/         # Testing and demo content
│   │       │   ├── contact.md     # Contact information
│   │       │   ├── resources.md   # General resources
│   │       │   └── test-autogenerate.md # Auto-generation demo
│   │       └── protected/         # Role-protected content
│   │           ├── member/         # Member+ access content
│   │           │   ├── benefits.md
│   │           │   ├── emergency-trusted-contact.md
│   │           │   ├── life-insurance-policies.md
│   │           │   ├── onboarding.md
│   │           │   └── team-guidelines.md
│   │           ├── coreteam/       # CoreTeam+ access content
│   │           │   ├── prospecting/
│   │           │   ├── setting-appointments/
│   │           │   ├── presentations/
│   │           │   ├── objections/
│   │           │   ├── products/
│   │           │   ├── recruiting-inviting/
│   │           │   ├── fast-start/
│   │           │   ├── promotions/
│   │           │   ├── tools-resources/
│   │           │   └── admin/
│   │           │       ├── guides/
│   │           │       │   ├── components/
│   │           │       │   │   ├── diagrams.mdx
│   │           │       │   │   ├── google-drive.mdx
│   │           │       │   │   └── videos.mdx
│   │           │       │   ├── creating-pages.md
│   │           │       │   ├── formatting.md
│   │           │       │   ├── index.md
│   │           │       │   ├── publishing-workflow.md
│   │           │       │   └── using-components.mdx
│   │           │       └── system/
│   │           │           ├── architecture.md
│   │           │           ├── authentication.md
│   │           │           ├── deployment.md
│   │           │           ├── development.md
│   │           │           └── security.md
│   │           └── admin/           # Admin-only content (archived)
│   ├── data/                        # Static data and utilities
│   │   └── pdfs.ts                # PDF metadata management utilities
│   ├── lib/                         # Core utilities and services
│   │   ├── auth.ts                 # JWT verification and authentication
│   │   ├── auth-client.ts          # Client-side authentication helpers
│   │   ├── config.ts               # Environment detection and configuration
│   │   ├── env.ts                  # Environment variable validation
│   │   ├── folder-utils.ts         # Google Drive folder utilities
│   │   ├── google-drive.ts         # Google Drive API integration
│   │   ├── nav.ts                  # Navigation generation utilities
│   │   └── README-google-drive.md  # Google Drive documentation
│   ├── layouts/                     # Page layout components
│   │   └── Layout.astro            # Main site layout wrapper
│   ├── pages/                       # Astro pages and API routes
│   │   ├── api/                    # API endpoints
│   │   │   ├── auth/
│   │   │   │   ├── login.ts        # OAuth login endpoint
│   │   │   │   ├── callback.ts     # OAuth callback handler
│   │   │   │   └── logout.ts       # Logout endpoint
│   │   │   ├── pdfs-dev/           # PDF file access endpoints
│   │   │   │   ├── index.ts        # PDF listing and search
│   │   │   │   └── [fileId].ts     # Individual PDF download
│   │   │   ├── test/               # Testing endpoints
│   │   │   │   └── drive-test.ts   # Google Drive testing
│   │   │   └── session.ts          # Session verification
│   │   └── index.astro             # Homepage
│   ├── route-middleware.ts          # Authentication middleware
│   ├── styles/                      # Styling
│   │   └── global.css              # Global CSS styles
│   └── utils/                       # Utility functions
│       ├── shortcodes/
│       │   ├── remark-d2-shortcodes.js
│       │   └── remark-video-shortcodes.js
├── vercel.json                     # Vercel deployment configuration
└── README.md                       # Main project documentation

🏗️ Architecture Overview

Astro Framework

• Static Site Generation: Pre-builds pages at build time
• Server-Side Rendering: For API routes and dynamic content
• Islands Architecture: Client-side JavaScript only where needed
• Content Collections: Type-safe content management

Starlight Documentation

• Documentation Site: Purpose-built for documentation
• Automatic Navigation: Generated from content structure
• Search: Built-in search functionality
• Theme: Dark/light mode with custom styling

Authentication Layer

• JWT-based: RS256 asymmetric encryption
• Role-based Access Control: Four-tier permission system
• OAuth Integration: Through auth.8531.ca gateway
• Middleware: Route-level authentication

📂 Key Directories Explained

/src/components/

Reusable UI components:

• AuthButton.astro: Handles login/logout UI with role-aware display
• GoogleDriveFolder.astro: Displays files from any Google Drive folder

/src/content/docs/

All site documentation organized by access level:

• public/: Everyone can access (Guest+)
• protected/member/: Team members and above
• protected/coreteam/: Core team and admins
• protected/admin/: Administrators only

/src/lib/

Core application logic:

• auth.ts: Server-side authentication utilities
• google-drive.ts: Google Drive API service
• config.ts: Environment and configuration management
• nav.ts: Dynamic navigation generation

/src/pages/api/

Serverless API endpoints:

• auth/: Authentication endpoints
• pdfs-dev/: Google Drive file access
• test/: Development testing utilities

/src/layouts/

Page templates and wrappers:

• Layout.astro: Main site layout with header, footer, navigation

🔧 Configuration Files

astro.config.mjs

Main Astro configuration:

• Integrations: Starlight, Vercel, Tailwind, MDX
• Output Mode: Server-side rendering for APIs
• Aliases: Import path shortcuts
• Security: CSP and header configuration

package.json

Project metadata and scripts:

• Dependencies: Production libraries
• Dev Dependencies: Development tools
• Scripts: Build, dev, test commands
• Type: Module (ESM)

vercel.json

Deployment configuration:

• Build Settings: How to build the project
• Routes: API routing configuration
• Headers: Security and CORS headers
• Functions: Serverless function settings

🎯 Key Features Implementation

Authentication System

1. Route Middleware (route-middleware.ts)

   • Validates JWT tokens
   • Enforces role-based access
   • Handles unauthenticated requests

2. Auth Client (auth-client.ts)

   • Client-side helpers
   • Token management
   • Login/logout flows

3. Auth Button (AuthButton.astro)

   • UI component for authentication
   • Role-aware display
   • Dropdown with user info

Google Drive Integration

1. Service Layer (google-drive.ts)

   • Google API client
   • File listing and downloading
   • Metadata parsing

2. API Endpoints (/api/pdfs-dev/)

   • File listing with pagination
   • Individual file access
   • Search and filtering

3. Display Component (GoogleDriveFolder.astro)

   • Reusable folder display
   • Preview/download buttons
   • Responsive grid layout

Content Management

1. Collections (content/config.ts)

   • Type-safe content schemas
   • Role and status validation
   • Custom frontmatter fields

2. Navigation (nav.ts)

   • Dynamic menu generation
   • Role-based filtering
   • Status-aware visibility

🔄 Data Flow

Authentication Flow

1. User clicks login
2. Redirect to auth.8531.ca
3. Google OAuth authentication
4. JWT token generation
5. Redirect back with token
6. Route middleware validates token
7. Content filtered by role

Content Rendering Flow

1. Astro builds static pages
2. Middleware validates access
3. Starlight renders documentation
4. Navigation filtered by role
5. API endpoints handle dynamic requests

Google Drive File Access

1. Component mounts with folder ID
2. API call to /api/pdfs-dev/
3. Service fetches from Google Drive
4. Files displayed in grid
5. Preview/download via direct links

🛡️ Security Architecture

Authentication Security

• RS256 JWTs: Asymmetric encryption
• HTTP-only Cookies: Prevent XSS
• SameSite: CSRF protection
• Short-lived Tokens: 1-hour expiration

Content Security

• Role-based Access: Four-tier system
• Content Status: Draft/review/published/archived
• File Access: Validated per request
• API Protection: All endpoints authenticated

Infrastructure Security

• HTTPS Only: Production enforcement
• Security Headers: X-Frame-Options, CSP
• CORS: Environment-specific policies
• Input Validation: TypeScript + Zod schemas

📊 Performance Considerations

Build Performance

• Static Generation: Pre-built pages
• Code Splitting: Automatic bundling
• Asset Optimization: Minification, compression
• Image Optimization: Responsive formats

Runtime Performance

• Edge Caching: Vercel’s global CDN
• API Caching: 5-minute response cache
• Lazy Loading: Client-side components
• Tree Shaking: Unused code removal

Monitoring

• Vercel Analytics: Built-in metrics
• Web Vitals: Core performance metrics
• Error Tracking: Centralized logging
• API Monitoring: Response times, error rates

🔄 Development Workflow

Adding New Content

1. Create .md file in appropriate directory
2. Add frontmatter with role/status
3. Write content (use ## for headings)
4. Test with different roles
5. Deploy when ready

Adding New Features

1. Plan feature and access requirements
2. Create components in /src/components/
3. Add API routes if needed
4. Update types and schemas
5. Test thoroughly
6. Document changes

Maintenance Tasks

• Dependencies: Regular updates and audits
• Security: Periodic reviews and patches
• Content: Review and archive outdated
• Performance: Monitor and optimize

This structure provides a scalable, maintainable foundation for the 8531 TeamSite with clear separation of concerns and comprehensive documentation.