Project Architecture and Features

Project Architecture and Features

Elevator Pitch

DreamLog is a private, voice-first dream journal. A user can save an original dream account, return to it, and optionally ask AI to organize or reflect on it. Creative visuals and evidence-backed recurring patterns extend that history without changing the original account.

Scope in the Current EGM Scoping Document

The current E-E output sets target capacity T = 5 rigorous features. It reports three alternative bases, and every one exceeds T:

Base	Story arc	Score	Rigorous nodes
C	Compare dream history, find recurring patterns, inspect evidence	35.0	6
B	Explore contrasting AI perspectives in a continuing forum discussion	20.0	6
A	Capture a dream, organize its account, and continue personal reflection	16.7	10

For an A-based route, the supplied stretch selections are A → D (creative visual, 1 new node), then A + D → C (pattern discovery, 3 more nodes). These are recorded architectural component counts, not effort estimates. 🔴 TODO [SCOPE-1/2]: Confirm that the route fits the team's capacity and that Arc D's one-node cost is supported. See LLM Exhibits for the audit and full E-E/E-F/E-G text.

Technical Stack

Layer	Proposed choice	Purpose
Native iOS client	Swift, SwiftUI, Xcode	iPhone application and navigation.
Device APIs	AVFoundation, Foundation URLSession	Save voice recordings, play them back, and call the backend.
Backend	Python + Starlette + Granian	Serve records and AI-processing endpoints using one course-supported stack.
Database	SQLite3	Local drafts; server records, source revisions, jobs, generated outputs, and threads.
Arc A speech	OpenAI Audio Transcriptions API	Turn accepted recordings into editable transcripts.
Arc A text generation	OpenAI Responses API	Organize dreams and produce reflection replies from permitted context.
Arc D visual generation, conditional	OpenAI Images API	Create an explicitly labeled creative image.
Arc C semantic matching, conditional	OpenAI Embeddings API + sqlite-vector	Find similar dream accounts if vector retrieval is chosen.

Only the dependencies proposed for the initial Arc A implementation are in the direct list in Getting Started; the D/C additions are labeled conditional there. Alternatives such as Apple Speech, Deepgram prerecorded transcription, and Anthropic Messages remain possible evaluations, not adopted dependencies.

Technical Plan

1. Preserve the source. Save the user's text or AVFoundation recording on the device before requesting AI work. Keep drafts and retry metadata in SQLite3. Audio, transcript, user corrections, and generated results have distinct identities.
2. Use recoverable processing. URLSession sends an authorized request to Starlette, served by Granian. A persistent SQLite3 job stores a stable request ID, dream ID, source revision, status, and retry count. A separate Python worker can process jobs without blocking capture. Reject late results after an edit, exclusion, or deletion.
3. Complete Arc A reflection. The current Arc A includes more than transcription: version tracking, source links, permission filtering, personal-history retrieval, AI reflection, and persistent conversation context are among its ten nodes. Record which current source revisions were actually supplied to each response. Recheck permission before sending retained context to an external API or resuming a thread.
4. Add Arc D only after A is stable. Use the Images API for a creative interpretation. Save generated images separately from the original dream and label them as imagined; delayed generation must not restore deleted material.
5. Add Arc C only after its scope is approved. Extract themes, propose semantic matches, preserve user-approved groups/corrections, and aggregate evidence from current permitted dream accounts. Keep visual details out of factual pattern evidence. Add embeddings and sqlite-vector only if the selected matching method needs vectors.

Detailed Implementation Plan

Stage	Deliverable	Completion check
1. Native journal	SwiftUI record list/detail/edit flows with local SQLite3 drafts.	A source dream survives app restart without an AI call.
2. Arc A capture	Voice recording, upload/retry state, transcription, and organized output.	Interrupted processing leaves the original recording and retry state intact.
3. Arc A reflection	Permissioned retrieval, source-linked responses, and resumable conversation.	A thread resumes with its goal and allowed context; edits and revoked access invalidate stale outputs.
4. Arc D stretch	Creative image generation using the specialized API.	A failed or late image job cannot alter the original account or block Arc A.
5. Arc C stretch	Theme extraction, semantic candidates, persistent grouping, and evidence aggregation.	Accepted corrections survive recomputation; patterns cite current permitted dreams.

Data Boundaries

Data	Rule
Original dream text/audio	User-authored source; generated output never overwrites it.
Transcript	Derived from audio; user corrections become a new source revision for later processing.
Summary, tags, replies, and images	Derived outputs linked to the source revision used to create them.
Personal notes and history	Included in AI context only under current permissions.
Pattern evidence	Uses current source accounts and accepted corrections, not generated images.
Deleted or excluded records	Cannot be restored or reused by a delayed job or retained context.

Alternatives Considered

• Other supported backends: Go + Echo, Rust + Axum, and TypeScript + Fastify remain valid course options. Python + Starlette + Granian is proposed for the API, job, and SQLite3 work; the team has not finalized it.
• Alternative bases: C and B each have 6 rigorous nodes; A has 10. The script ranks them but does not establish a capacity-compliant base under T = 5.
• Recognition and LLM providers: Apple Speech, Deepgram, and Anthropic are possible comparisons. The OpenAI APIs are the current proposal, with provider/model evaluation still required.
• Vector retrieval: Arc C requires semantic matching, but the method is open. Embeddings plus sqlite-vector are conditional choices, not an automatic requirement of SQLite3.

Decisions Still Needed

• 🔴 TODO [SCOPE-1]: Resolve the scope-versus-capacity mismatch: every reported base exceeds T = 5.
• Confirm the base and stretch sequence before treating D or C APIs as direct dependencies.
• Confirm Python + Starlette + Granian and choose API models after accuracy, cost, latency, and privacy evaluation.
• Define authentication, hosting, retention, deletion, and the iOS deployment target before processing real dream data.
• Assign owners and verify build/run instructions from a clean checkout.