|
| 1 | +# Next.js Project Structure Overview: AI Workshops Platform |
| 2 | + |
| 3 | +This Next.js application is an educational platform for AI workshops, primarily designed for CoderDojo events. It provides an interactive chat interface where users can work through data analysis exercises with AI assistance. |
| 4 | + |
| 5 | +## Core Technologies & Dependencies |
| 6 | + |
| 7 | +### Main Framework |
| 8 | + |
| 9 | +- **Next.js** with App Router architecture |
| 10 | +- **React** for UI components |
| 11 | +- **TypeScript** for type safety |
| 12 | + |
| 13 | +### AI Integration |
| 14 | + |
| 15 | +- **Azure OpenAI Service** for GPT-based conversational AI |
| 16 | +- **Azure Dynamic Sessions** for secure Python code execution |
| 17 | + |
| 18 | +See `package.json` for the complete dependency list with specific versions. |
| 19 | + |
| 20 | +## Authentication |
| 21 | + |
| 22 | +### Concept of the Authentication System |
| 23 | + |
| 24 | +- The Admin can create and manage workshops, generating access codes _per workshop_, that work within a time frame. |
| 25 | +- The user signs in with this access code to join a workshop, granting access to all exercises. |
| 26 | +- The user can log out on the exercise overview to end their session. |
| 27 | + |
| 28 | +### The Auth API |
| 29 | + |
| 30 | +The authentication system uses two main API endpoints: |
| 31 | + |
| 32 | +#### POST /api/auth/login |
| 33 | + |
| 34 | +- Accepts workshop access code |
| 35 | +- Validates code against workshop database |
| 36 | +- Checks time constraints (30 minutes before start to 30 minutes after end) |
| 37 | +- Creates encrypted session using Iron Session |
| 38 | +- Returns authentication status |
| 39 | + |
| 40 | +#### POST /api/auth/logout |
| 41 | + |
| 42 | +- Destroys current session |
| 43 | +- Clears authentication cookies |
| 44 | +- Redirects to login page |
| 45 | + |
| 46 | +#### Session Management |
| 47 | + |
| 48 | +- Uses Iron Session with encrypted cookies |
| 49 | +- Two session types: App sessions (auth) and Chat sessions (conversation state) |
| 50 | +- Session validation includes time-bound workshop access |
| 51 | +- Automatic re-authentication when sessions expire |
| 52 | + |
| 53 | +### The Admin Interface and Workshop Management API |
| 54 | + |
| 55 | +#### Workshop Management UI (`/workshops`) |
| 56 | + |
| 57 | +- Create new workshops with time constraints |
| 58 | +- Generate unique access codes |
| 59 | +- View workshop status and participant access |
| 60 | +- Admin authentication via special workshop code |
| 61 | + |
| 62 | +#### Workshop API Endpoints |
| 63 | + |
| 64 | +- `GET /api/workshops` - List all workshops (admin only) |
| 65 | +- `POST /api/workshops` - Create new workshop |
| 66 | +- `PUT /api/workshops/[id]` - Update workshop details |
| 67 | +- `DELETE /api/workshops/[id]` - Delete workshop |
| 68 | + |
| 69 | +#### Workshop Schema |
| 70 | + |
| 71 | +```typescript |
| 72 | +interface Workshop { |
| 73 | + id: string; |
| 74 | + name: string; |
| 75 | + code: string; // Access code for participants |
| 76 | + startDateTime: Date; // Workshop start time |
| 77 | + endDateTime: Date; // Workshop end time |
| 78 | + description?: string; |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +## The Exercise System |
| 83 | + |
| 84 | +### Concept of the Exercise System |
| 85 | + |
| 86 | +- Exercises are modular and can be added or modified easily. |
| 87 | +- Each exercise has a system prompt, a collection of data files, and a task sheet. |
| 88 | + |
| 89 | +**Exercise Structure:** |
| 90 | +Each exercise is organized in the `/prompts/` directory with the following structure: |
| 91 | + |
| 92 | +```text |
| 93 | +prompts/ |
| 94 | +├── exercises.json # Central registry of all exercises |
| 95 | +└── [exercise-folder]/ # Individual exercise directories |
| 96 | + ├── system-prompt.md # AI assistant instructions |
| 97 | + ├── welcome-message.md # Initial chat message |
| 98 | + ├── tasksheet.md # Exercise description for users |
| 99 | + └── *.csv # Data files for analysis |
| 100 | +``` |
| 101 | + |
| 102 | +**Exercise Configuration (`exercises.json`):** |
| 103 | + |
| 104 | +```json |
| 105 | +{ |
| 106 | + "exercises": { |
| 107 | + "data-cave": { |
| 108 | + "title": "Die Daten-Höhle", |
| 109 | + "folder": "01-data-cave", |
| 110 | + "difficulty": "easy", |
| 111 | + "summary": "Description of the exercise...", |
| 112 | + "system_prompt_file": "system-prompt.md", |
| 113 | + "welcome_message_file": "welcome-message.md", |
| 114 | + "data_files": "data-cave.csv", |
| 115 | + "image": "/images/covers/01-data-cave.svg" |
| 116 | + } |
| 117 | + } |
| 118 | +} |
| 119 | +``` |
| 120 | + |
| 121 | +**Exercise Loading Process:** |
| 122 | + |
| 123 | +1. Main page loads `exercises.json` to display available exercises |
| 124 | +2. User selects an exercise → navigates to `/chat/[exercise]` |
| 125 | +3. Chat interface loads exercise-specific system prompt and data files |
| 126 | +4. AI assistant is initialized with exercise context |
| 127 | + |
| 128 | +### The Chat Interface |
| 129 | + |
| 130 | +**Real-time Chat UI** (`/chat/[exercise]`) |
| 131 | + |
| 132 | +The chat interface provides an interactive environment where users communicate with an AI assistant to solve data analysis exercises. |
| 133 | + |
| 134 | +**Key Features:** |
| 135 | + |
| 136 | +- **Real-time Streaming:** Server-Sent Events (SSE) for live AI responses |
| 137 | +- **System Prompt Access:** Users can view the AI's instructions via dropdown menu |
| 138 | +- **Task Sheet Modal:** Exercise description and requirements |
| 139 | +- **Code Execution:** AI can generate and run Python code for data analysis |
| 140 | +- **File Processing:** Dynamic integration of exercise data files |
| 141 | +- **Message History:** Persistent conversation state within session |
| 142 | + |
| 143 | +**Data Flow:** |
| 144 | + |
| 145 | +1. User enters message |
| 146 | +2. Message sent to `/api/chat` with exercise context |
| 147 | +3. AI processes message with system prompt and data files |
| 148 | +4. Streaming response updates UI in real-time |
| 149 | +5. Code execution results (if any) displayed inline |
| 150 | + |
| 151 | +### The Chat API |
| 152 | + |
| 153 | +#### Main Endpoint: POST /api/chat |
| 154 | + |
| 155 | +Handles all chat interactions with the AI assistant. |
| 156 | + |
| 157 | +**Request Parameters:** |
| 158 | + |
| 159 | +- `message`: User's input message |
| 160 | +- `exercise`: Exercise identifier (from URL parameter) |
| 161 | +- `previousResponseId`: Conversation continuity token |
| 162 | + |
| 163 | +**Processing Pipeline:** |
| 164 | + |
| 165 | +1. **Authentication:** Validate user session and workshop access |
| 166 | +2. **Exercise Loading:** Fetch exercise configuration and data files |
| 167 | +3. **Context Building:** Combine system prompt with data file previews |
| 168 | +4. **AI Interaction:** Send to Azure OpenAI with streaming response |
| 169 | +5. **Code Execution:** Process any Python code via Dynamic Sessions |
| 170 | +6. **Response Assembly:** Stream chunks to client with session management |
| 171 | + |
| 172 | +#### Code Interpreter tool with Azure Dynamic Sessions |
| 173 | + |
| 174 | +The platform integrates Azure Dynamic Sessions to provide secure Python code execution capabilities for the AI assistant. |
| 175 | + |
| 176 | +##### What are Azure Dynamic Sessions? |
| 177 | + |
| 178 | +- Secure, isolated Python execution environments |
| 179 | +- Automatically managed compute resources |
| 180 | +- File system access for data processing |
| 181 | +- Safe execution of AI-generated code |
| 182 | +- Returns execution results and standard output/error streams |
| 183 | + |
| 184 | +## Data Privacy & Security |
| 185 | + |
| 186 | +- All data is stored and processed either publicly on GitHub or on Azure servers in Europe. |
| 187 | +- The whole application is open-source. |
0 commit comments