Repository navigation
Project Architecture and Features
Status: design proposal based on E-A, E-C, E-D, and the Arc A/Arc C scope in the local
EGMScoping.mdsource (excluded from the published wiki). The native iOS constraint and SQLite3 come from the team's stated stack. Python + Starlette + Granian and the external AI APIs are recommendations; no application implementation is present yet.
DreamLog is a private, voice-first dream journal. A user saves an original dream account, revisits it later, and may optionally generate a transcript, summary, or reflection. Saving the dream must work even when AI processing fails.
- E-A: Preserve dreams people care about; interview frequencies are not proof of app demand.
- E-C/E-D: Build capture and journal first, keep original records separate from AI output, and support optional reflection with inspectable context. Forum, patterns, sleep integration, images, and video are later features.
- Arc A: Voice recording, recoverable transcription, and organized output form the initial workflow.
- Arc C: A resumable supportive conversation about a selected dream is the proposed first stretch goal. It uses that dream and its thread; permitted-history retrieval is a later scope.
| Layer | Proposed choice | Purpose |
|---|---|---|
| iOS client | Swift, SwiftUI, Xcode | Native iPhone application. |
| Native iOS APIs | AVFoundation, Foundation URLSession
|
Record audio, retain a local file, and send requests to the back end. |
| Back end | Python + Starlette + Granian | HTTP API and processing jobs, using one of the course-supported stacks. |
| Database | SQLite3 on device for drafts; SQLite3 on server for canonical records | Preserve sources, revisions, jobs, and conversation turns. |
| Speech recognition | OpenAI Audio Transcriptions API | Transcribe saved recordings; the transcript remains editable. |
| LLM | OpenAI Responses API | Generate summaries/tags and Arc C replies from permitted source material. |
| Optional later retrieval | sqlite-vector | Add only if semantic history search or pattern matching is implemented. |
The exact direct-dependency links are listed in Getting Started. There is no need for sqlite-vector in the initial Arc A + Arc C workflow.
Recommended speech API: OpenAI Audio Transcriptions, with gpt-4o-mini-transcribe as an initial model to evaluate. It accepts a saved audio file, fitting Arc A's save-then-process sequence. The team should compare its transcription quality on dream narratives and supported languages before fixing the model.
Recommended LLM API: OpenAI Responses for optional summary/tag extraction and Arc C conversation turns. The Python back end holds the API key and submits only the selected dream, current transcript/revision, and allowed thread context. The specific text model remains a team decision.
Other viable providers to evaluate are Apple's native Speech framework or Deepgram prerecorded transcription for speech recognition, and Anthropic Messages for text generation. These are alternatives, not direct dependencies in the proposed stack. Apple Speech availability can vary by language and may require an Internet connection, so it needs device/language testing before adoption.
- Save before processing. SwiftUI writes the original text or AVFoundation recording to local app storage and records its pending state in SQLite3. An interrupted network request cannot discard the source.
-
Transfer for requested cloud processing. Foundation
URLSessionuploads the saved source to Starlette when the user requests transcription or reflection. Granian serves the API. The server stores audio in a restricted file area and keeps record metadata, current revision, and processing status in SQLite3. Authentication and remote-storage policy must be settled before real user data is uploaded. - Run recoverable jobs. Persist a job ID, record ID, source revision, status, and attempt count before calling an external API. A separate Python worker can retry jobs without blocking HTTP requests. Accept a result only if the dream still exists and the revision still matches.
- Keep AI output derived. Save transcripts, summaries, tags, and replies separately from the user-authored dream. A correction creates a new revision and marks older outputs stale. A deletion prevents delayed results from restoring the record.
- Add Arc C after capture works. Store a thread's selected dream, user goal, messages, and context choice. A reflection failure must not block recording or reading a saved dream. History retrieval and vector search are outside this first stretch goal.
| Stage | Deliverable | Completion check |
|---|---|---|
| 1. Native journal | SwiftUI create/list/edit/delete screens with local SQLite3 drafts. | A saved draft survives app restart without any API call. |
| 2. Arc A recording | AVFoundation recording, URLSession upload, Starlette endpoint, SQLite3 job, and transcription. |
An interrupted upload or failed transcription leaves the original recording available and retryable. |
| 3. Organized output | Optional transcript correction and summary/tags linked to a source revision. | A late job cannot overwrite a user correction or deleted dream. |
| 4. Arc C stretch | A resumable conversation about one selected dream using the Responses API. | The thread resumes with its goal and context choice; AI failure leaves Arc A usable. |
| 5. Later scopes | Evaluate history retrieval, patterns, forum, visuals, and sleep integration separately. | The team approves new scope and direct dependencies before they enter Getting Started. |
| Data | Rule |
|---|---|
| Original dream text/audio | User-authored source; never replace it with generated text. |
| Transcript | Derived from audio; user corrections become the current revision. |
| Summary/tags | Generated output linked to the exact source revision. |
| Reflection thread | Persist user goal, messages, and selected context for safe resumption. |
| Deleted or excluded records | Reject late jobs and keep them out of future AI context. |
- Other course-supported back ends: Go + Echo, Rust + Axum, and TypeScript + Fastify remain valid team choices. Python + Starlette + Granian is proposed because the backend work is largely API orchestration, file processing, and SQLite3 access; it is not yet a team decision.
- Base Arc B or F: The scoping output puts each at six rigorous nodes, above the target capacity of five. Arc A has four and is the smaller base workflow.
- Native Apple Speech: It is a possible speech-recognition route, but availability and language support must be checked on target devices. The current proposal uses server-side transcription so jobs can be retried against a saved file.
-
Vector retrieval: SQLite3 without
sqlite-vectoris sufficient for the selected-dream Arc C flow. Add the extension only if later history search requires embeddings.
- Confirm Python + Starlette + Granian as the team's back-end choice.
- Choose the iOS deployment target and test recording permissions and audio file format.
- Define authentication, server hosting, audio retention, and deletion policy before using real dream data.
- Evaluate transcription accuracy, latency, cost, and privacy for the target languages and choose an LLM model.
- Assign implementation owners and verify build/run steps from a clean checkout.