About

This is the ARKOS ("Automated Resource Knowledge Base OS") frontend. It's a productivity-centric Svelte web app, and it currently has four pages:

• a landing page
• an about page
• a dashboard (static for now)
• a calendar-only view
• a chat-only view

This repo was split from https://github.com/SGIARK/ARKOS which was formerly a monorepo. The latter now only contains the backend.

Tech stack

Languages

• TypeScript
• Svelte

Production dependencies

• SvelteKit
• @event-calendar/core
• ajv

Dev dependencies

• Prettier
• ESLint
• Vitest
• @testing-library/svelte
• vitest-fetch-mock

Todo list

Pre-MVP

• Add CI to this repo
• Add authentication (primarily MIT Touchstone, possibly others)
• Make the UI more user-friendly when the backend returns a malformed response
• Testing cleanup
  • Mock components (both library and ARK2.0-specific)
  • Mock user-generated content (maybe randomize?)
  • Determine code coverage
    • Figure out how .c8rc or .nycrc work so we can remove unnecessary files from the report
• Fine-tune the CSS to look nicer
  • Figure out visual brand identity (fonts? colors? logo?)

Post-MVP

• Additional pages
  • user settings page? (eg dark/light mode, etc)
  • Some way for users to submit feedback?
  • Task list tracking?
    • Specifically track assignments/classwork and their due dates?
• Mobile-friendliness?

Installation

Slow

1. Install node.js if you don’t have it already.
2. Install npm if you don’t have it already.
3. Install git if you don’t have it already.
4. cd into your favorite folder.
5. Clone the entire repo using git clone https://github.com/SGIARK/arkos-webui.
6. Type cd arkos-webui.
7. Install the dependencies using npm install.
8. Run npm run dev, then immediately hit the O key, to launch the (currently rather sparse) frontend in your web browser.

Quick

Open a terminal window, copy-paste this entire code block, and hit enter. Be warned: this assumes you already installed node.js, npm, and git, that you have cd'd into your favorite folder, and that you use VS Code as your code editor.

git clone https://github.com/SGIARK/arkos-webui
cd arkos-webui
npm install
npm run ci-all
npm run dev
code .

File structure

(As of September 11, 2025.)

• .gitignore
• .npmrc
• .prettierignore
• .prettierrc
• config-frontend.json (a JSON config object with exactly one key)
• eslint.config.js
• package-lock.json
• package.json
• README.md (this very file!)
• schemas (for JSON schemas)
  • chatcompletionrequest_schema.json
  • chatcompletionresponse_schema.json
  • chatmessage_schema.json
• src (all the actual frontend code goes here!)
  • app.d.ts
  • app.html
  • components
    • Calendar.svelte (shows the calendar view)
    • chat.svelte (shows the chat view)
    • navbar.svelte (static navbar)
  • lib
    • index.ts (currently empty but kept as a placeholder)
    • schema_types.ts (for type declarations)
  • routes
    • about
      • +page.svelte (static about page)
    • calendar
      • +page.svelte
    • chat
      • +page.svelte
    • dashboard
      • +page.svelte
    • +page.svelte (static landing page)
• static
  • favicon.png (placeholder for right now)
  • styles.css
• svelte.config.js
• test
  • components
    • Calendar.test.ts (for testing src/components/Calendar.svelte)
    • chat.test.ts (for testing src/components/chat.svelte)
  • routes
    • calendar.test.ts
    • chat.test.ts
  • mock-backend.ts (creates the mock backend)
  • mock-backend.test.ts (for testing the aforementioned mock backend)
• tsconfig.json
• vite.config.ts
• vitest-setup-client.ts

Contributing

As always, make a pull request.

Style + quality guidelines

Before submitting your pull request, please do the following checks.

• Run the test cases using npm test. They should all pass; if not, you should fix the ones that fail.
• Typecheck everything using npm run typecheck. There should be no output; otherwise TypeScript is complaining, and you should fix the type error(s) it identifies.
• Lint everything using npx eslint **/*. The output should be empty; if not, you should fix the issue(s) identified.
• Reformat everything using npx prettier **/* --write.
• Finally, try using the new version of the UI yourself by running npm run dev to make sure it isn’t subtly broken in some way.

Note that npm run ci-all is a quick shorthand for running the first four checks, in that order.

Components

If your page or component code becomes too long or unwieldy, consider splitting it into another component. Since we are NOT building a single-page app, ask yourself if it could also plausibly be an entire page instead.

Appearance

All CSS styles live in static/styles.css for the time being. You can add a <link> tag within the <svelte:head> directive if you need to add more CSS.

If you plan on making major changes to the UI, please first try the new version yourself. If possible, let the other ARKOS team members try it. Keep in mind that a great UI can often be just one CSS rule or one stray HTML tag away from an abysmal one.

Automated testing

We use Vitest as our test runner; see the test folder for some examples.

All test code should go in the test/ folder. Do NOT put any test code in the src folder. This makes it easy to review test code at a glance. Tests for src/components/ go in test/components/ and tests for src/routes/ go in test/routes/.

As a general rule of thumb, most .svelte and .ts files in the src folder need a corresponding test suite. However, this excludes app.d.ts, TypeScript type declarations, and static Svelte components or routes.

To test a dynamic Svelte component, write one test per HTML tag. Static HTML tags do not need to be tested. If the content or children of a certain tag can vary, write multiple tests for that tag using input space partitioning. Again, keep in mind that even one HTML tag can sometimes make or break the entire UX.

JSON schemas

Schemas go in schemas/. This is intentionally a repo top-level folder because double-checking responses and requests are malformed is also very useful for backend-side code.

Use ajv to validate data against a schema. Don't roll your own validator, because it'll probably be a lot flakier. Make sure to type your validator with ValidateFunction<T> instead of just ValidateFunction, so that you can convince TypeScript can narrow the data's type for you.

Since the frontend and backend repo are now independent, make sure to keep the schemas synced for now. There may be a more elegant solution though in the long term.

Helpful links if you get stuck

Documentation

• ESLint
• MDN web
  • HTML
  • CSS
  • JavaScript
  • Request: useful when developing or testing the mock backend
  • Response: also useful for the mock backend
• Prettier
• Svelte
• SvelteKit
• Testing Library
  • queries
  • @testing-library/svelte
• TypeScript
• Vitest
• @event-calendar GitHub repo
• ajv API reference
  • ajv guide
• vitest-fetch-mock README

Others

• MIT SIPB Mattermost server
  • ARK channel
• StackOverflow
• ChatGPT
• Claude.ai