System Requirements Document (SRD)

Project Name: cosmic-cadre

1. Introduction

The cosmic-cadre project is a web-based platform designed to provide civil service professionals in Nigeria with a tailored testing experience. Users can manually input their cadre and level in the civil service hierarchy (e.g., Level 8–17), and the system will generate unique, non-repeating questions based on their level. The platform is fully automated, leveraging AI to handle question generation, shuffling, scoring, and feedback.

This document outlines the system requirements for cosmic-cadre, ensuring a seamless, bug-free experience for users.

2. System Overview

The cosmic-cadre system is a single-page web application that enables users to take a timed test tailored to their civil service level. The system dynamically generates 70 unique questions based on the user's cadre and level, with difficulty scaling appropriately. Users have 40 minutes to complete the test, after which the system automatically submits their answers, calculates their score, and displays the correct answers.

Key features include:

• AI-driven question generation and shuffling.
• No login or authentication required for users.
• Real-time scoring and feedback.
• A clean, intuitive interface optimized for simplicity and efficiency.

The system is designed to cater to Nigerian civil service professionals, ensuring relevance and accessibility.

3. Functional Requirements

User Stories:

• As a User, I should be able to manually enter my cadre and level in the civil service hierarchy.
• As a User, I should be presented with 70 unique, non-repeating questions tailored to my cadre and level.
• As a User, I should have 40 minutes to complete the test.
• As a User, I should see one question at a time, with shuffled answer options.
• As a User, I should have my answers automatically submitted when the timer runs out.
• As a User, I should see my score immediately after the test.
• As a User, I should be able to view the correct answers to all questions after the test.

4. User Personas

1. Civil Service Professional

• Description: Individuals working in the Nigerian civil service, ranging from Level 8 to Level 17.
• Goals: To test their knowledge and skills relevant to their cadre and level.
• Pain Points: Limited time and need for tailored, relevant questions.
• Behavior: Prefers simplicity and efficiency, with minimal distractions.

5. Visuals Colors and Theme

Color Palette:

The design will reflect professionalism with a touch of vibrancy to engage users.

• Background: #F5F9FF (soft sky blue for a calming effect).
• Surface: #FFFFFF (clean white for clarity).
• Text: #2C3E50 (deep navy for readability).
• Accent: #FF6F61 (warm coral for highlights and buttons).
• Muted Tones: #BDC3C7 (light gray for secondary elements).

6. Signature Design Concept

Interactive Galaxy Map Homepage

The homepage will feature an interactive galaxy map where each star represents a cadre level (e.g., Level 8–17). Users can hover over a star to see a brief description of the level and click to start their test. The galaxy will have subtle animations, with stars twinkling and orbiting dynamically.

Upon clicking a star, the screen will transition into a "warp speed" animation, immersing users in the experience. The test interface will have a clean, minimalist design, with a timer displayed prominently at the top and questions appearing one at a time in a card-like format.

Micro-interactions include:

• Hover effects on stars that expand slightly and glow.
• Smooth transitions between sections.
• Subtle animations for buttons and progress indicators.

This design ensures the platform is memorable and engaging while maintaining a professional tone.

7. Non-Functional Requirements

• Performance: The system must load questions and calculate scores within 2 seconds.
• Scalability: The AI should handle up to 10,000 concurrent users without degradation.
• Reliability: The system must maintain 99.9% uptime.
• Security: All data processing must occur server-side to ensure user privacy.
• Accessibility: The platform must be usable on both desktop and mobile devices.

8. Tech Stack

Frontend:

• React for Web

Backend:

• Python
• FastAPI

Database:

• MySQL (with Alembic for migrations)

AI Models:

• GPT 5.4 for user-friendly response
• Claude 4.6 Opas for academic or coding work

AI Tools:

• Litellm for LLM Routing
• Langchain

Orchestration:

• Docker for local orchestration
• Kubernetes for server-side orchestration

9. Assumptions and Constraints

Assumptions:

• Users will have access to a stable internet connection.
• The AI will generate questions relevant to the Nigerian civil service context.
• No login or authentication is required, simplifying user access.

Constraints:

• The system must adhere to a 40-minute test duration.
• Questions must be unique and non-repeating for each test session.
• The platform must operate within Nigerian timezone settings (WAT).

10. Glossary

• Cadre: A group of civil service professionals categorized by their role and responsibilities.
• Level: A rank within the civil service hierarchy, ranging from Level 8 to Level 17.
• AI: Artificial Intelligence, used for generating and managing questions.
• WAT: West Africa Time, the timezone for Nigeria.