_{A Modern Cross-Platform Collaborative Learning & Study Environment powered by A.I built for UCCians 1st year 1st semester finals project in ComProg I}

An offline first terminal study suite made in pure C integrating proven learning methodologies (Pomodoro, Active Recall, Spaced Repetition) with local SQLite storage and Google Gemini generative intelligence.

---

Tech Stack

---

Architecture Overview

SUCCESS is engineered around a Multi-Tier Decoupled Terminal Architecture (N-Tier Pattern). By separating display rendering from application domain logic, operating system syscalls, and network I/O, the codebase achieves complete cross-platform portability without compromising performance or code clarity.

flowchart TD
    %% Theme-Agnostic High-Contrast Node Styles (WCAG AA Compliant)
    classDef client fill:#5865F2,stroke:#3C45A5,stroke-width:2px,color:#FFFFFF;
    classDef tui fill:#00599C,stroke:#003B57,stroke-width:2px,color:#FFFFFF;
    classDef feature fill:#D97706,stroke:#92400E,stroke-width:2px,color:#FFFFFF;
    classDef compat fill:#059669,stroke:#065F46,stroke-width:2px,color:#FFFFFF;
    classDef vault fill:#7C3AED,stroke:#5B21B6,stroke-width:2px,color:#FFFFFF;
    classDef external fill:#8E75B2,stroke:#5B21B6,stroke-width:2px,color:#FFFFFF;

    %% Ingress Terminal Viewport
    Terminal["<b>Terminal Viewport</b><br/>(Alacritty • Kitty • Windows Terminal • WezTerm)"]:::client

    %% Core Application Boundary
    subgraph Engine ["<b>SUCCESS Platform Runtime Engine</b>"]
        direction TB

        %% Row 1: Presentation Layer
        UI["<b>NCurses / PDCurses Windowing Layer</b><br/>• Double-buffered frame blitting<br/>• UTF-8 unicode border glyphs"]:::tui

        %% Row 2: Business & Study Modules
        subgraph Features ["<b>Core Study Modules</b>"]
            direction LR
            Timer["<b>Pomodoro Timer</b><br/>Hardware Sleep"]:::feature
            Todo["<b>Todo Manager</b><br/>Task Tracking"]:::feature
            Social["<b>Social Hall</b><br/>Resource Hub"]:::feature
            AI["<b>AI Suite</b><br/>Chat • Quiz • Cards"]:::feature
        end

        %% Row 3: Cross-Platform Hardware & OS Abstraction
        subgraph Abstraction ["<b>OS & Hardware Abstraction Layer</b>"]
            direction LR
            Compat["<b>compat.c</b><br/>• Non-blocking I/O<br/>• Sleep & mkdir"]:::compat
            Paths["<b>paths.c</b><br/>• Dynamic env.json<br/>• Endpoint fallback"]:::compat
            NFD["<b>nfd_compat.c</b><br/>• Zenity / Win32<br/>• Terminal fallback"]:::compat
        end

        UI --> Features
        Features --> Abstraction
    end

    %% Transparent background adapts cleanly to GitHub Light, Dark, and Mobile
    style Engine fill:none,stroke:#5865F2,stroke-width:2px,stroke-dasharray: 5 5

    %% Target Backends
    DB[("<b>Local SQLite3 Storage</b><br/>• users.db (Auth)<br/>• todos.db (Tasks)<br/>• resources.db (Posts)")]:::vault
    Gemini["<b>Google Gemini Cloud</b><br/>• gemini-2.5-flash<br/>• Resumable File Protocol"]:::external

    %% Ingress & Egress Connections
    Terminal <-->|ANSI VT100 / Raw Termios| UI
    Features -->|ACID SQL Transactions| DB
    AI -->|HTTPS REST API via libcurl| Gemini

Loading

---

Project Structure

success/
├── CMakeLists.txt                                   # Root cross-platform CMake build configuration
├── env.json.example                                 # Template for Gemini API credential setup
├── .gitignore                                       # Version control ignore definitions
├── db/                                              # Local SQLite database directory (auto-created)
│   ├── users.db                                     # User accounts, credentials, and roles
│   ├── todos.db                                     # User task records and completion states
│   ├── resources.db                                 # Social Hall academic materials and notes
│   └── .session                                     # Active authentication session cache
├── include/                                         # Project headers
│   └── win32/                                       # Isolated Windows-specific SDK headers (PDCurses/pthreads)
├── src/                                             # Application source code
│   ├── Makefile                                     # GNU Makefile with automatic OS detection
│   ├── curses.c                                     # Main TUI application entry point
│   ├── main.c                                       # CLI fallback entry point
│   ├── callbacks/
│   │   └── write_callback.c                         # Memory buffer handler for libcurl streams
│   ├── features/
│   │   ├── ai_chat.c                                # Interactive AI academic chatbot
│   │   ├── flashcard.c                              # AI active recall flashcard generator
│   │   ├── quiz.c                                   # AI 20-question multiple choice exam maker
│   │   ├── social_hall.c                            # Student/Teacher resource sharing hub
│   │   ├── study_timer.c                            # Low-power Pomodoro countdown timer
│   │   └── todo.c                                   # SQLite todo and assignment tracker
│   ├── gemini_api/
│   │   ├── gemini_request.c                         # JSON payload builder & response parser
│   │   ├── get_file_uri.c                           # Multimodal attachment handler
│   │   └── get_upload_url.c                         # Google Resumable Media Upload protocol
│   ├── pages/
│   │   ├── introduction.c                           # Welcome splash, authentication, role routing
│   │   ├── menu.c                                   # Student / Teacher dashboard navigation
│   │   └── tools.c                                  # Academic tools selection sub-menu
│   ├── utils/
│   │   ├── compat.c / .h                            # Cross-platform primitives (sleep, kbhit, mkdir)
│   │   ├── paths.c / .h                             # Unified env.json & credential resolver
│   │   ├── nfd_compat.c                             # Native file dialog abstraction & CLI fallback
│   │   ├── get_file_mime_type.c                     # Document & image MIME detection
│   │   ├── read_file_b64.c                          # Base64 file encoder for attachments
│   │   └── grep_string.c                            # Safe HTTP header parser
│   └── vendor/
│       └── cjson/                                   # Vendored official MIT cJSON v1.7.19 parser
└── tests/
    └── test_suite.c                                 # Automated 39-case headless regression test harness

---

Installing Tools and Dependencies

To build and run SUCCESS, you need a C compiler (GCC or Clang), CMake (or Make), SQLite3, libcurl, and NCurses (or PDCurses on Windows).

Arch-based Distros (CachyOS / Arch / Manjaro)

sudo pacman -S base-devel cmake ncurses curl sqlite

Debian / Ubuntu-based Distros

sudo apt update && sudo apt install -y build-essential cmake libncurses-dev libcurl4-openssl-dev libsqlite3-dev

Fedora-based Distros

sudo dnf install -y gcc gcc-c++ cmake ncurses-devel libcurl-devel sqlite-devel

macOS (Homebrew)

brew install cmake ncurses curl sqlite3

Windows 10/11

The recommended approach for Windows is using MSYS2 or modern package managers.

Option A: MSYS2 (MinGW-w64) — Recommended

Launch the MSYS2 UCRT64 or MINGW64 shell and run:

pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-pdcurses mingw-w64-x86_64-curl mingw-w64-x86_64-sqlite3

Option B: Winget

Install tools from PowerShell / CMD:

winget install Kitware.CMake -e --accept-source-agreements
winget install LLVM.LLVM
winget install Git.Git

Option C: Scoop

scoop install git cmake gcc curl sqlite

---

Configuration (AI Features)

Prerequisites

To use the AI Chatbot, Quiz Generator, and Flashcard Generator, obtain a free Google Gemini API Key from Google AI Studio.

Important

Never commit or publicly share your API key. Keep env.json listed in .gitignore.

Method 1: Environment Variable (Recommended for quick testing)

export GEMINI_API_KEY="paste-your-gemini-api-key-here"

Method 2: Configuration File

Create an env.json file in the root project directory:

{
  "GEMINI_API_KEY": "paste-your-gemini-api-key-here"
}

---

Build and Run

Building with CMake (Recommended)

1. Configure the build directory:

cmake -B build

2. Compile all targets:

cmake --build build

This compiles three executables into build/:

• build/success: Full interactive NCurses TUI application.
• build/success_cli: Command-line fallback interface.
• build/test_suite: Automated headless test runner.

Alternative: Building with GNU Make

make -C src

---

Running the Application

Launch the full interactive TUI:

./build/success

Execute the headless test harness to verify your installation:

./build/test_suite

Note

For the best visual experience, ensure your terminal emulator supports UTF-8 and ANSI colors with a minimum resolution of 80 columns × 24 rows (recommended: 100 × 30).

---

PROJECT PREVIEW

video demo (v0.1.10)

success-demo.mp4

success terminal preview linux environment kitty terminal emulator (v0.1.10)

---

License

This project is licensed under the terms of the GNU General Public License v3.0.