OSIT-AE-App-Svelte/README.md

# One Sky IT's Aether App - SvelteKit v2

This uses SvelteKit version 2.x with Svelte version 5.x, DexieJS 4.x, TailwindCSS 4.1, and Skeleton.

# Modules

## Core (`/core/`)

Admin-only views for foundational Aether objects. Minimal UI — primarily used for data management.

- **Accounts** (`/core/accounts/`, `/core/accounts/[account_id]/`)
- **Activity Logs** (`/core/activity_logs/`)
- **Addresses** (`/core/addresses/`, `/core/addresses/[address_id]/`)
- **Contacts** (`/core/contacts/`, `/core/contacts/[contact_id]/`)
- **Lookups** (`/core/lookups/`) — Countries, subdivisions, time zones
- **People** (`/core/people/`, `/core/people/[person_id]/`)
- **Sites** (`/core/sites/`, `/core/sites/[site_id]/`)
- **Users** (`/core/users/`, `/core/users/[user_id]/`)

## Events (`/events/`)

The primary client-facing module for conference and event management.

### Event List (`/events/`)

### Event Detail (`/events/[event_id]/`)

Each event has four sub-modules, each in its own SvelteKit route group:

#### Presentation Management (`/(pres_mgmt)/`)

Manages the full conference program.

- `/events/[event_id]/pres_mgmt/` — Dashboard
- `/events/[event_id]/locations/` — Location list
- `/events/[event_id]/location/[event_location_id]/` — Location detail
- `/events/[event_id]/presenter/[presenter_id]/` — Presenter detail
- `/events/[event_id]/session/[session_id]/` — Session detail
- `/events/[event_id]/reports/` — Presenter, session, and file reports

#### Launcher (`/(launcher)/`)

Kiosk display system; runs on-site to show session schedules and presenter info.

- `/events/[event_id]/launcher/` — Launcher home
- `/events/[event_id]/launcher/[event_location_id]/` — Location-specific display

#### Badges (`/(badges)/`)

Badge printing and management for event attendees.

- `/events/[event_id]/badges/` — Badge list
- `/events/[event_id]/badges/[badge_id]/` — Badge detail
- `/events/[event_id]/badges/[badge_id]/print` — Print a single badge
- `/events/[event_id]/badges/[badge_id]/review` — Review before printing
- `/events/[event_id]/badges/print_list/` — Bulk print queue
- `/events/[event_id]/badges/stats/` — Badge statistics
- `/events/[event_id]/templates/` — Badge template management

#### Leads (`/(leads)/`)

Exhibitor lead capture via QR scan or manual entry.

- `/events/[event_id]/leads/` — Exhibit list
- `/events/[event_id]/leads/exhibit/[exhibit_id]/` — Exhibit detail and lead capture
- `/events/[event_id]/leads/exhibit/[exhibit_id]/lead/[exhibit_tracking_id]/` — Lead detail

#### Event Settings (`/settings/`)

- `/events/[event_id]/settings/` — Event configuration (basic info, pres mgmt, badges, abstracts)

## Journals (`/journals/`)

The "frontier" module — most fully-featured and used as the canonical implementation reference.

- `/journals/` — Journal list
- `/journals/[journal_id]/` — Journal detail and entry list
- `/journals/[journal_id]/entry/[journal_entry_id]/` — Journal entry detail and editor

## IDAA (`/idaa/`)

Custom module for the IDAA client. Built on core Aether objects (Events, Posts, Archives).

- `/idaa/` — IDAA home / dashboard

### Archives (`/idaa/archives/`)

- `/idaa/archives/` — Archive list with media player
- `/idaa/archives/[archive_id]/` — Archive detail and content list

### Bulletin Board (`/idaa/bb/`)

Built on the Posts and Post Comments objects.

- `/idaa/bb/` — Post list
- `/idaa/bb/[post_id]/` — Post detail and comments

### Recovery Meetings (`/idaa/recovery_meetings/`)

Built on the Events object.

- `/idaa/recovery_meetings/` — Meeting list with search/filter
- `/idaa/recovery_meetings/[event_id]/` — Meeting detail

### Video Conferences (`/idaa/video_conferences/`)

- `/idaa/video_conferences/` — Video conference list (Jitsi integration)
- `/idaa/jitsi_reports/` — Jitsi usage reports

## Hosted Files (`/hosted_files/`)

- `/hosted_files/` — File list and upload management
- `/hosted_files/video_util/` — Video processing utility

## Testing (`/testing/`)

Developer sandbox pages — not for production use.

- `/testing/ae_obj_field_editor_v3/` — V3 field editor playground
- `/testing/data_store_v3/` — Data store V3 playground
- `/testing/editor_test/` — CodeMirror / TipTap editor tests
- `/testing/hosted_files/` — File upload tests

# How to build and deploy SvelteKit:

The deployment is now fully automated using Docker Compose. The application is built directly from source inside a clean Docker environment, eliminating the need for manual `rsync` or `npm_deploy` management.

### Commands

Run these commands from the root of the `aether_app_sveltekit` project:

#### 1. Deploy to Staging (Dev)
This builds and restarts the staging containers (`ae_app_node_dev`, etc.) on your local workstation.
```bash
npm run deploy:staging
```

#### 2. Deploy to Production
This builds the image using production flags and restarts the production containers.
```bash
npm run deploy:prod
```

### Technical Details

- **Dockerfile**: Uses a multi-stage build. Stage 1 (builder) installs dependencies and builds the app using the `BUILD_MODE` argument. Stage 2 (runtime) creates the final lightweight image.
- **Environment Handling**: 
    - `PUBLIC_` variables are baked into the image during the build step based on `.env.staging` or `.env.prod`.
    - Private runtime variables are passed via the `env_file` in `docker-compose.yml`.
- **Networking**: Containers are automatically joined to the `ae_dev_net` network to allow local Nginx proxying.
- **Legacy Migration**: The `upstream` in the local Nginx configuration has been updated to point to these new SvelteKit containers on port 3000.

---

# Rebuild the node_modules directory and manually install extra Svelte packages

Run the npm update to fix the node_modules directory and package.json

```bash
npm list
npm outdated
npm update
npm outdated
npm list
```

Other installs?:
Are both still needed? I know at least one of these is. 2024-07-23

```bash
npm install --save-dev svelte-highlight
npm install --save-dev typescript-svelte-plugin
```

---

# Set up and run

## Packages and dependencies

```bash
npm install --save-dev svelte-highlight typescript-svelte-plugin
npm install flowbite flowbite-svelte tailwind-merge @popperjs/core
```

I am slowly switching from Font-Awesome to Lucide

## Tiptap Editor

- Eventually use Edra? https://edra.tsuzat.com/
    - Best Rich Text Editor, made for Svelte Developers with Tiptap
    - ShadEditor is "evolving" to be Edra.
- ShadCN is still stuck on Tailwind 3. Waiting to upgrade to Tailwind 4.x. Tailwind 4.x was released in late January 2025. ShadCN is still being worked on as of late March 2025.
- [https://github.com/huntabyte/shadcn-svelte/issues/1643](https://github.com/huntabyte/shadcn-svelte/issues/1643)

Need to install ShadCN and Lucide for the Tiptap editor.

```bash
npm install shadcn-svelte
npm install lucide-svelte
npm install mode-watcher
```

Now we initialize the ShadCN and ShadEditor packages. Follow the command line instructions.

```bash
npx shadcn-svelte@next init
npx shadcn-svelte@next add dropdown-menu button tooltip input popover separator
npx shadeditor init
```

More packages related to the Tiptap editor???

```bash
npm install @tiptap/extension-link @tiptap/extension-bullet-list @tiptap/extension-history @tiptap/extension-typography @tiptap/extension-underline
```

## Build

## Environment file

### ".env"

This is the default used if others are not found when when "npm run dev" or "npm run build" is run.

### ".env.local"

This is used when "npm run dev" is run. This is not used in the production build.

### ".env.production"

This is used when "npm run build" is run. This is not used in the development build.

### ".env:prod"

This is modified to allow for a staging environment and production environment built.

### ".env:staging"

This is modified to allow for a staging environment and production environment built.

### Example Important Values when running in dev:

Note: Environment values need to be updated when our home IP address changes. Be sure to check the Aether Container Environment and Aether Node App (SvelteKit) Environment files for the correct IP address. The Node Docker environment needs to be updated here and in the .env file that Docker will read. This needs to be improved later...

```bash
DOCKER_AE_API_DEV_SERVER_EXTRA_HOST=dev-api.oneskyit.com:108.48.200.147

DOCKER_AE_API_SERVER_EXTRA_HOST=dev-api.oneskyit.com:108.48.200.147

PUBLIC_AE_API_SERVER=api.oneskyit.com
PUBLIC_AE_API_BAK_SERVER=bak-api.oneskyit.com
```

# create-svelte

Everything you need to build a Svelte project, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).

## Creating a project

If you're seeing this, you've probably already done this step. Congrats!

```bash
# create a new project in the current directory
npm create svelte@latest

# create a new project in my-app
npm create svelte@latest my-app
```

## Developing

Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

## Building

To create a production version of your app:

```bash
npm run build
```

You can preview the production build with `npm run preview`.

> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.