System Requirements Document for pure-orbit

1. Introduction

This document is the requested product specification for pure-orbit, an application that helps vocational training instructors in Algeria prepare a module plan and a lesson plan. The plans are based on the instructor’s selected specialty and module and on the reference files they provide.

The attached plan examples are authoritative for the shape and organization of their tables only. Their subject matter and visible text must not be reused as plan content. Plan content varies by specialty and module.

Success criteria

The product succeeds when an instructor can establish an account, provide a specialty and module plus the relevant reference files, create both types of plan from those inputs, and return to review and continue working on saved plans. Generated plans must reflect the table structures of the supplied examples without copying their content.

2. System Overview

pure-orbit is a custom web application for one accepted human persona: the vocational training instructor. It provides public entry and identity access, then protected workspaces for managing reference sources and creating, reviewing, and continuing saved module and lesson plans.

The application uses AI-assisted generation to produce plans from instructor-provided inputs and reference files. The attached images are structure references, not content sources: the application must not treat their example text as reusable plan content. The named reference types include fiche de présentation du module, PE (programme d'etude), fiche de présentation des compétences complémentaires, and structure du programme.

The provisioned runtime consists of a React frontend, a shared FastAPI backend, MariaDB for application-owned persistent data, a LiteLLM gateway for backend model-provider calls, and PostgreSQL supporting LiteLLM. Feature APIs and domain modules belong in the shared backend; the LiteLLM-supporting PostgreSQL is distinct from application-owned storage.

Removed from scope

• Reusing the attached examples’ content as plan content (also: copying template content)

2a. Product Interpretation and Delivery Boundary

The supplied ordered page contract is the current information architecture: Landing, Login, Dashboard, Sources, Module Plan, Lesson Plan, and Plans. Landing is public. Login is the anonymous identity-entry surface for self-registration and returning verification. The remaining pages require login and support the instructor’s private, persistent work.

The instructor establishes an application-owned identity through self-registration and verifies that identity on return to resume saved files and plans. This identity continuity is required to keep each instructor’s durable work associated with the correct person; it does not imply differentiated roles or permissions.

Current scope is limited to preparing module and lesson plans from specialty/module details and the instructor’s reference files, preserving the examples’ table structures while excluding their content. No additional product capabilities are assumed.

2c. Page Content and Component Coverage

Landing

• Information and state: Public explanation in Arabic that the application helps vocational training instructors prepare module and lesson plans from their own specialty-specific inputs and reference files. Show a blank table preview that communicates structure only.
• Primary actions: Continue to Login to register or verify identity.
• Supporting components: RTL headline and numbered preparation cue; a flat, empty plan-table preview; a concise numbered path from specialty and sources through module and lesson plans.
• Domain entities: None required on the public page.
• States: Loading is not applicable to static entry content. If the page cannot load, show a recoverable error and allow retry. Success is the instructor reaching Login; continuation is registration or returning verification there.

Login

• Information and state: Anonymous identity-entry surface with distinct self-registration and returning verification paths. Do not expose protected plans or files before identity is established.
• Primary actions: Register as a new instructor or verify identity as a returning instructor.
• Supporting components: Clearly labeled identity inputs and submission feedback; no invitation or administrator workflow.
• Domain entities: Application identity and session, as required for private saved work.
• States: Show submission progress, successful establishment or verification, and a clear error for invalid or unavailable submission. Allow correction and retry. On success, continue to Dashboard.

Dashboard

• Information and state: Protected continuation point showing the instructor’s saved work and routes to source preparation, plan creation, and saved-plan review.
• Primary actions: Continue to Sources, Module Plan, Lesson Plan, or Plans.
• Supporting components: Saved-work summary and clear empty state when no plans have yet been saved.
• Domain entities: Instructor-owned saved sources and plans.
• States: Loading while saved work is retrieved; empty state for a new instructor; success when work is available; recoverable retrieval error with retry. Continue to the relevant work page.

Sources

• Information and state: Protected workspace for entering the specialty and module and attaching the reference files used to prepare plans. Identify the named reference types: fiche de présentation du module, PE (programme d'etude), fiche de présentation des compétences complémentaires, and structure du programme.
• Primary actions: Enter specialty and module details and attach the available reference files.
• Supporting components: Editorial file rows with file type/name and upload status; upload progress and confirmation; source list and specialty/module context.
• Domain entities: Specialty, module, and instructor-provided reference files.
• States: Empty state before sources are added; loading/progress during upload; success when a file is attached; error for failed or unusable upload with a retry path. Preserve entered context when recoverable. Continue to either plan page.

Module Plan

• Information and state: Protected creation and editing workspace for a module plan based on the selected specialty, module, and reference files. Use the attached examples’ table structure, not their content.
• Primary actions: Generate a module plan from the available inputs and review or edit the resulting plan.
• Supporting components: Numbered progress cues; structured, clearly headed table with fine borders and readable cells; source context; generation and save feedback.
• Domain entities: Specialty, module, reference files, and module plan.
• States: Empty or not-ready state when required inputs are absent; loading during generation; success when a plan is produced and saved; error when generation or saving fails, with retry and preservation of recoverable work. Continue to review the plan, create a lesson plan, or return to Plans.

Lesson Plan

• Information and state: Protected creation and editing workspace for a lesson plan based on the instructor’s specialty/module context and reference files. Use the attached examples’ table structure, not their content.
• Primary actions: Generate a lesson plan from the available inputs and review or edit the result.
• Supporting components: Numbered progress cues; structured table with readable headings and cells; source context; generation and save feedback.
• Domain entities: Specialty, module, reference files, and lesson plan.
• States: Empty or not-ready state when required inputs are absent; loading during generation; success when a plan is produced and saved; error when generation or saving fails, with retry and preservation of recoverable work. Continue to review the plan or return to Plans.

Plans

• Information and state: Protected list of the instructor’s saved plans, allowing them to reopen plans for review and editing.
• Primary actions: Select a saved plan and reopen it in its corresponding Module Plan or Lesson Plan workspace.
• Supporting components: Distinguishable plan type and specialty/module context; empty state when no plans are saved.
• Domain entities: Instructor-owned module and lesson plans.
• States: Loading while plans are retrieved; empty state when none exist; success when saved plans are listed and reopened; recoverable retrieval error with retry. Continue reviewing or editing the selected plan.

3. Functional Requirements

1. As a vocational training instructor, I should be able to understand the application’s purpose before starting protected work.

   • Provenance: required_inference — public entry is specified by the page contract.
   • Lifecycle and access: From anonymous Landing, the instructor reads that the application supports module and lesson plan preparation from their own inputs and reference files, then proceeds to Login.
   • Observable acceptance: Landing explains the accepted purpose and offers a path to identity access; it does not expose protected files or plans.
   • Failure and continuation: If entry content fails to load, the instructor can retry. On success, continue to Login.

2. As a vocational training instructor, I should be able to register and verify my identity on return so I can access my saved plans and files.

   • Provenance: required_inference — explicitly accepted in Planning Scope as the minimum identity continuity needed for durable, private work.
   • Lifecycle and access: From anonymous Login, a new instructor self-registers; a returning instructor verifies identity. Successful identity establishment or verification opens the protected Dashboard and associates the instructor with their saved work.
   • Observable acceptance: A new instructor can establish an identity; a returning instructor can regain access to their own saved work.
   • Failure and recovery: Invalid or unavailable submissions produce a clear error and allow correction or retry. Protected work remains unavailable until identity is established or verified.
   • Continuation: Continue to Dashboard. No administrator invitation or adjacent account-management capability is implied.

3. As a vocational training instructor, I should be able to provide a specialty, module, and reference files for plan preparation.
   • Provenance: explicit for using the named reference files and varying plan content by specialty and module; required_inference for the Sources page and persistent association needed to resume work.
   • Lifecycle and access: After login, the instructor enters specialty and module context and attaches available files, including fiche de présentation du module, PE (programme d'etude), fiche de présentation des compétences complémentaires, and structure du programme.
   • Observable acceptance: The selected specialty/module and attached files are available as inputs to plan preparation and remain associated with the instructor’s work.
   • Failure and recovery: Upload progress and success are visible. A failed or unusable upload is reported and can be retried; preserve recoverable entered context.
   • Continuation: Continue to Module Plan or Lesson Plan.

4. As a vocational training instructor, I should be able to create a module plan from my specialty, module, and reference files.
   • Provenance: explicit for creating a module plan from the reference files and varying content by specialty and module; required_inference for generation, review, and saving mechanics needed to make the plan usable and resumable.
   • Lifecycle and access: From protected Module Plan, the instructor uses the selected context and available reference files to request a plan, then reviews and edits the result.
   • Observable acceptance: A module plan is produced from the instructor’s inputs and follows the table structure of the attached examples without reusing their content. The plan is saved to the instructor’s work.
   • Failure and recovery: Missing inputs are identified before generation. Generation or saving failure is visible; the instructor can retry and recover available work.
   • Continuation: Continue reviewing/editing, create a lesson plan, or reopen the plan from Plans.

5. As a vocational training instructor, I should be able to create a lesson plan from my specialty, module, and reference files.

   • Provenance: explicit for creating a lesson plan from the reference files and varying content by specialty and module; required_inference for generation, review, and saving mechanics needed to make the plan usable and resumable.
   • Lifecycle and access: From protected Lesson Plan, the instructor uses the selected context and available reference files to request a plan, then reviews and edits the result.
   • Observable acceptance: A lesson plan is produced from the instructor’s inputs and follows the table structure of the attached examples without reusing their content. The plan is saved to the instructor’s work.
   • Failure and recovery: Missing inputs are identified before generation. Generation or saving failure is visible; the instructor can retry and recover available work.
   • Continuation: Continue reviewing/editing or reopen the plan from Plans.

6. As a vocational training instructor, I should be able to review and continue work on my saved plans.

   • Provenance: required_inference — the page contract specifies saved-plan listing, reopening, review, and editing as the continuation path for durable work.
   • Lifecycle and access: From protected Plans or Dashboard, the instructor selects a saved plan and reopens it in its corresponding plan workspace.
   • Observable acceptance: The instructor can distinguish and reopen saved module and lesson plans associated with their specialty/module context.
   • Failure and recovery: Retrieval errors are visible and retryable; an empty collection is clearly represented.
   • Continuation: Continue reviewing or editing the selected plan.

4. User Personas

مكوّن/مدرّس التكوين المهني

• Product context: An instructor preparing vocational training materials for specialties and modules in Algeria. This is the sole accepted active-human persona; the role is a required_inference from the requested application and its accepted workflows.
• Primary goal: Produce usable module and lesson plans whose content reflects the selected specialty/module and the instructor’s reference files.
• Distinct responsibilities: Provide specialty and module context; attach the relevant program and competency documents; create and review both plan types; return to saved work to continue.
• Relevant inputs and decisions: Chooses the specialty and module, supplies the available reference files, and reviews the generated plan content. The attached examples guide table structure only.
• Interactions with other accepted participants: None. No other active human participant is established by the source.
• Observable success: Both plan types can be prepared from the instructor’s own inputs, retain the examples’ table structure without copying their content, and remain available for later review.

5. Core User Flows

1. First visit and identity establishment

1. The instructor opens Landing anonymously and sees the application’s purpose and a blank structural table preview.
2. The instructor proceeds to Login and chooses self-registration.
3. The instructor submits the identity information required to establish application identity.
4. On success, the application establishes the instructor’s identity and opens Dashboard. Protected plans and files are available only after this point.
5. If submission fails, the instructor sees an error, corrects the input or retries, and remains outside protected work until registration succeeds.

2. Returning to saved work

1. The returning instructor opens Login and submits the information needed to verify their identity.
2. On successful verification, the application restores access to that instructor’s saved files and plans and opens Dashboard.
3. The instructor continues to Plans to reopen a saved plan, or to Sources, Module Plan, or Lesson Plan to continue preparation.
4. If verification fails or the service is unavailable, the instructor sees an error and can correct or retry; protected work remains unavailable until verification succeeds.

3. Prepare reference sources

1. From Dashboard, the instructor opens Sources.
2. The instructor enters the specialty and module for the work.
3. The instructor attaches the available reference files, including fiche de présentation du module, PE (programme d'etude), fiche de présentation des compétences complémentaires, and structure du programme.
4. The application shows upload progress and confirms successful attachments.
5. If an upload fails, the instructor sees which attachment did not complete and can retry; recoverable specialty/module context is retained.
6. The instructor continues independently to Module Plan or Lesson Plan.

4. Create a module plan

1. The instructor opens Module Plan, from Dashboard or after preparing sources.
2. The instructor uses the selected specialty/module and available reference files as the plan inputs.
3. The instructor requests module-plan generation.
4. The application produces a plan using the attached examples’ table structure, without copying their content.
5. The instructor reviews and edits the result; the application saves it to the instructor’s work.
6. If required inputs are missing, the application identifies that state and the instructor returns to Sources. If generation or saving fails, the instructor sees an error and can retry or recover available work.
7. The instructor continues reviewing the plan, proceeds to Lesson Plan, or later reopens it from Plans.

5. Create a lesson plan

1. The instructor opens Lesson Plan, from Dashboard or after preparing sources.
2. The instructor uses the selected specialty/module and available reference files as the plan inputs.
3. The instructor requests lesson-plan generation.
4. The application produces a plan using the attached examples’ table structure, without copying their content.
5. The instructor reviews and edits the result; the application saves it to the instructor’s work.
6. If required inputs are missing, the application identifies that state and the instructor returns to Sources. If generation or saving fails, the instructor sees an error and can retry or recover available work.
7. The instructor continues reviewing the plan or later reopens it from Plans.

6. Reopen and continue a saved plan

1. The instructor opens Plans or reaches saved work from Dashboard.
2. The application lists the instructor’s saved plans, distinguishing module and lesson plans and showing their specialty/module context.
3. The instructor selects a plan; the application opens it in Module Plan or Lesson Plan, as appropriate.
4. The instructor reviews or edits the plan and continues work.
5. If retrieval fails, the instructor sees a recoverable error and can retry. If no plans exist, the application shows an empty state and the instructor can continue to Sources to begin preparing inputs.

6. Visuals Colors and Theme

Creative direction: Typographic infrastructure for vocational teaching. Muse: Erik Spiekermann. The visual language should communicate institutional clarity and practical efficiency for vocational instructors in Algeria. The attached images inform table structure only; do not reproduce their content.

• Light-mode palette: Background #F3F0E8; surface #FFFEFA; text #202624; primary #245B46; accent #C84A32; muted #77786F.
• Color roles: Warm paper background and light work surfaces; dark ink for text; deep green for primary actions and progress; terracotta for limited alerts or emphasis. Do not place small text on terracotta.
• Typography: IBM Plex Sans Arabic for headings and Latin data such as PE and MC; Noto Sans Arabic for body text and tables. Arabic headings are strong, weight 650–700, with RTL alignment.
• Type scale: 1.25 scale. Display heading clamp(2.75rem, 6vw, 5.5rem) with a 44px mobile size; section headings 32/26/22px; interface text 16px; table labels at least 14px.
• Shape and layout: Editorial geometry, square or lightly rounded 4px corners, fine dividers, stable column alignment, and visible numbering. Use RTL layout, organized columns, and consistent margins. A sidebar may become top navigation or a collapsible menu on mobile.
• Tables and responsive behavior: Treat tables as working documents, not decorative cards. Use clearly labeled columns, fine borders, and varied row heights. On narrow screens, use readable stacked rows or intentional horizontal scrolling; do not compress cells or clip text.
• Imagery: The interface and documents are the primary imagery. Use simple line icons for files, upload, and review. Do not add stock photography or unrelated illustrations.
• Responsive readability: At 375px, 768px, and 1280px, keep all readable text and controls fully within their viewport and containers. Wrap or scale content as needed. Intentional scrolling is acceptable when every item can be brought fully into view.

7. Signature Design Concept

Build the public Landing hero as an editorial composition rather than a generic SaaS dashboard. Place a large, right-aligned Arabic headline on a light paper block, occupying roughly half the desktop width. Pair it with a large, flat preview of an empty plan table drawn with fine ink lines and lightly tinted green column headings. The preview communicates table structure only and contains no copied text from the attached examples.

Set a deep-green bar behind the action heading and place a clear primary action beneath it. Use a small terracotta stage number as the only limited accent. On mobile, stack the headline, table preview, and action in that order; scale the headline from 44px so words and controls remain fully visible.

8. Interaction Model & Motion Direction

Interaction Model: Animated
Motion Tempo: restrained
Hero Dimensionality: flat

Landing Hero Motion Brief

• Focal subject: The empty, structured plan-table preview beside the Arabic headline.
• Input → transformation → outcome: The instructor chooses to begin; the interface directs them from the public explanation to identity access, the entry point for preparing plans from their own specialty and reference files.
• Motion vocabulary: Functional transitions of 150–200ms for step changes and source-save confirmation; numbered progress markers remain stable. No continuous decorative motion.
• First frame: A composed, static editorial layout with the headline on the right, blank table preview beside it, and the primary action clearly visible.
• Reduced-motion state: Remove nonessential transitions and retain a usable static layout. Keep any scrollable content accessible through wrapping or intentional horizontal scrolling.

9. Non-Functional Requirements

1. Readable, responsive interface

   • Provenance: explicit — creative direction.
   • Keep readable text and controls whole and accessible at 375px, 768px, and 1280px. Use wrapping, scaling, stacked rows, or intentional scrolling rather than clipping or shrinking table text below the specified minimum.

2. Arabic and RTL presentation

   • Provenance: explicit — creative direction and product context.
   • Support RTL layout and Arabic typography, while rendering Latin reference labels such as PE and MC legibly.

3. Reduced-motion accessibility

   • Provenance: explicit — creative direction.
   • Respect prefers-reduced-motion by removing unnecessary transitions and preserving a usable static arrangement.

4. Private durable work

   • Provenance: required_inference — Planning Scope requires durable state and application-owned identity so instructors can return to their saved plans and files.
   • Associate saved work with the verified instructor identity and prevent access to protected work before identity verification. This does not establish differentiated permissions or roles.

5. Faithful table structure without content reuse

   • Provenance: explicit — user requirement.
   • Use the attached examples as references for table shape only. Do not reuse their subject matter or visible example content as generated plan content.

10. Tech Stack

• Frontend: React application UI, as provisioned.
• Backend: Shared FastAPI process for application APIs and domain modules, as provisioned. Add feature routes and modules within this process rather than introducing separate services for plan APIs.
• Application-owned persistent storage: MariaDB, as provisioned, for instructor-owned identity-linked sources and saved plans.
• AI gateway: LiteLLM, as provisioned, for backend model-provider calls supporting plan generation.
• LiteLLM supporting database: PostgreSQL, as provisioned and separate from application-owned storage.
• Deployment: Preserve the provisioned service inventory and reuse the shared backend. No additional process is specified by the accepted workflows.

11. Assumptions and Constraints

• Constraint — template use: The attached images are authoritative only as structure references. Their content must not be copied into generated plans.
• Constraint — variable plan content: Plan content varies according to the selected specialty and module.
• Constraint — reference basis: Plans are based on instructor-provided files, including fiche de présentation du module, PE (programme d'etude), fiche de présentation des compétences complémentaires, and structure du programme.
• Assumption — identity continuity: Self-registration and returning verification are required to associate durable files and plans with the correct instructor. No invitation or administrator provisioning workflow is assumed.
• Assumption — generation details: The source does not specify a model provider, file-format restrictions, or a detailed generation algorithm. The provisioned LiteLLM gateway is used for backend model-provider calls; no additional provider-specific behavior is assumed.
• Boundary: No additional personas, differentiated permissions, or adjacent account-management capabilities are established.

12. Glossary

• Module plan: A plan for a vocational training module, prepared from the selected specialty/module context and reference files.
• Lesson plan: A lesson-level plan prepared from the selected specialty/module context and reference files.
• PE (programme d'etude): A named reference program file supplied for plan preparation.
• Fiche de présentation du module: A module presentation sheet used as a reference input.
• Fiche de présentation des compétences complémentaires: A complementary competencies presentation sheet used as a reference input.
• Structure du programme: A program-structure reference file used as an input.
• Table structure: The organization and visual arrangement of a plan’s table, distinct from the example content shown in the attached images.