Finca Audio Phase 2 - Technical Task Breakdown

Executive Summary

Project: Extend Finca Audio with report editing, sharing, attachments, PDF export, projects, and file organization.

Team: 2 senior developers


Stage Dependencies & Parallelization

┌─────────────────────────────────────────────────────────────┐
│  PARALLEL TRACK A          PARALLEL TRACK B                 │
│  ─────────────────         ─────────────────                │
│  Stage 0 (Report Fixes)    Stage 1 (Attachments)            │
│       │                    Stage 2 (Report Sharing)         │
│       ▼                         │                           │
│  Stage 3 (PDF Export)           │                           │
│       │                         │                           │
│       └─────────┬───────────────┘                           │
│                 ▼                                           │
│         Stage 4 (Projects)                                  │
│                 │                                           │
│                 ▼                                           │
│         Stage 5 (Project RBAC)                              │
│                 │                                           │
│                 ▼                                           │
│         Stage 6 (File Organization)                         │
└─────────────────────────────────────────────────────────────┘

User Stories

IDStoryStage
US-0.1As a user, I can see all tabs including Metadata for reports with custom fields0
US-0.2As a user, I see custom fields rendered as readable text, not raw JSON0
US-0.3As a user, I can edit custom fields in reports just like standard fields0
US-1.1As an admin, I can attach reference documents to prompt templates1
US-1.2As a user, analyses using templates with attachments include that context1
US-2.1As an admin, I can grant specific users read-only access to specific reports2
US-2.2As a report viewer, I can only see reports I’ve been granted access to2
US-2.3As a report viewer, I can view source files for reports I have access to2
US-3.1As a user, I can export any report as a professional PDF3
US-4.1As a user, I can organize my work into projects4
US-4.2As a user, I can switch between projects and see only that project’s content4
US-5.1As an admin, I can control who has access to which projects5
US-5.2As a project viewer, I can see but not edit project content5
US-6.1As a user, I can organize files into folders within a project6
US-6.2As a user, I can control file visibility (private/project/org)6

Stage 0: Report Fixes

Goal: Fix three bugs blocking end users from fully using reports with custom fields.

Total Hours: 22-26h (including QA)

Epic 0.1: Metadata Tab Fix

Task IDTaskDescriptionHoursDepsPriority
0.1.1Diagnose tab visibilityTrace useTabAvailability.js logic, confirm root cause is missing custom field check1h-High
0.1.2Fix tab availability logicUpdate hasMetadata check to include custom_fields presence2h0.1.1High

Files: client/src/features/multi-analysis/hooks/useTabAvailability.js

Epic 0.2: JSON Display Fix

Task IDTaskDescriptionHoursDepsPriority
0.2.1Audit JsonBlock renderingDocument which field types fall through to JSON.stringify1h-High
0.2.2Improve generic field renderingRender string fields as prose, objects as labeled sections3h0.2.1High
0.2.3Add persona card componentCreate PersonaCard.jsx for synthesized_personas display3h0.2.2Medium

Files: client/src/features/multi-analysis/components/JsonBlock.jsx, client/src/features/multi-analysis/components/PersonaCard.jsx (new)

Epic 0.3: Custom Fields Editing

Task IDTaskDescriptionHoursDepsPriority
0.3.1Add custom field edit stateExtend useMultiAnalysisState with editCustomFields state2h-High
0.3.2Create editable field componentBuild EditableCustomField.jsx with textarea for JSON/text3h0.3.1High
0.3.3Wire editing to OverviewTabAdd edit buttons and save handlers for custom fields2h0.3.2High
0.3.4Handle nested object editingSupport editing individual fields within persona objects3h0.3.3Medium

Files: client/src/features/multi-analysis/hooks/useMultiAnalysisState.js, client/src/features/multi-analysis/components/EditableCustomField.jsx (new), client/src/features/multi-analysis/components/tabs/OverviewTab.jsx

Epic 0.4: Testing & QA

Task IDTaskDescriptionHoursDepsPriority
0.4.1Stage 0 functional testingTest with existing reports (Women/Men Persona Analysis), verify all fixes3h0.1.2, 0.2.3, 0.3.4High
0.4.2Cross-browser QATest in Chrome, Firefox, Safari2h0.4.1Medium

Demo Criteria: Open Women Persona Analysis report → all tabs visible → personas render as cards → can edit persona description → save persists.


Stage 1: Reference Attachments

Goal: Attach PDF/text files to prompt templates as LLM context.

Total Hours: 34-40h (including QA)

Epic 1.1: Data Model

Task IDTaskDescriptionHoursDepsPriority
1.1.1Design template_attachments schemaTable with template_id, file metadata, S3 key2h-High
1.1.2Create TemplateAttachment modelSQLAlchemy model with relationship to PromptTemplate2h1.1.1High
1.1.3Write Alembic migrationCreate table with constraints (max 5 attachments, valid content types)2h1.1.2High

Files: api/src/shared/db_models.py, api/migrations/versions/xxx_add_template_attachments.py

Epic 1.2: Backend API

Task IDTaskDescriptionHoursDepsPriority
1.2.1Add S3 attachment helpersUpload/download functions in storage.py for attachments prefix2h-High
1.2.2Upload attachment endpointPOST /prompts/{id}/attachments - multipart upload4h1.1.3, 1.2.1High
1.2.3List attachments endpointGET /prompts/{id}/attachments - with presigned URLs2h1.2.1High
1.2.4Delete attachment endpointDELETE /prompts/{id}/attachments/{att_id} - remove from S3 + DB2h1.2.1High
1.2.5Download attachment endpointGET /prompts/{id}/attachments/{att_id}/download - presigned URL1h1.2.1Medium

Files: api/src/shared/storage.py, api/src/routers/prompts.py

Epic 1.3: Analysis Integration

Task IDTaskDescriptionHoursDepsPriority
1.3.1Fetch attachments in analysisLoad template attachments when running analysis2h1.1.3High
1.3.2Include attachments in LLM callAdd PDF/text as user messages before transcript4h1.3.1High
1.3.3Handle PDF base64 encodingConvert PDF to base64 for OpenAI vision2h1.3.2High

Files: api/src/handlers/analysis.py, api/src/handlers/multi_analysis.py

Epic 1.4: Frontend

Task IDTaskDescriptionHoursDepsPriority
1.4.1Add attachments section to editorNew card in PromptTemplateEditor for attachments3h1.2.3High
1.4.2Implement file upload UIDrag-drop or click-to-upload with validation3h1.2.2High
1.4.3Attachment list with actionsDisplay attachments with download/delete buttons2h1.2.4High

Files: client/src/pages/PromptTemplateEditor.jsx

Epic 1.5: Testing & QA

Task IDTaskDescriptionHoursDepsPriority
1.5.1Upload/download testingTest file upload, S3 storage, download URLs2h1.4.3High
1.5.2Analysis with attachmentsRun analysis with PDF attachment, verify LLM receives context3h1.3.3High
1.5.3File size/type validationTest rejection of invalid files, size limits2h1.5.1Medium

Demo Criteria: Upload PDF to template → run analysis → results reference PDF content → can download/delete attachment.


Stage 2: Report Sharing

Goal: Allow inviting users who can view specific reports but not edit.

Total Hours: 42-50h (including QA)

Epic 2.1: Data Model

Task IDTaskDescriptionHoursDepsPriority
2.1.1Design report_access schemaDefine table with polymorphic report reference (analysis_run_id OR multi_analysis_id)2h-High
2.1.2Create ReportAccess modelAdd SQLAlchemy model in db_models.py2h2.1.1High
2.1.3Write Alembic migrationCreate table with indexes, constraints2h2.1.2High
2.1.4Add report_viewer roleAdd to UserRole enum or handle as special case1h2.1.2High

Files: api/src/shared/db_models.py, api/migrations/versions/xxx_add_report_access.py

Epic 2.2: Backend API

Task IDTaskDescriptionHoursDepsPriority
2.2.1Create reports routerNew routers/reports.py for access management endpoints2h2.1.3High
2.2.2Grant access endpointPOST /reports/{type}/{id}/access - add users to report3h2.2.1High
2.2.3Revoke access endpointDELETE /reports/{type}/{id}/access/{user_id}2h2.2.1High
2.2.4List access endpointGET /reports/{type}/{id}/access - list users with access2h2.2.1High
2.2.5Update analysis access checksModify can_view_report() in analyses router for report_viewer3h2.1.4High
2.2.6Update file access checksAllow report_viewers to view files for their granted reports3h2.2.5High

Files: api/src/routers/reports.py (new), api/src/routers/analyses.py, api/src/routers/files.py, api/src/deps.py

Epic 2.3: Frontend - Share Dialog

Task IDTaskDescriptionHoursDepsPriority
2.3.1Create ShareReportDialogDialog to grant/revoke access from report detail page4h2.2.4High
2.3.2Add share button to AnalysisDetailsIntegrate ShareReportDialog with single-file analysis2h2.3.1High
2.3.3Add share button to MultiAnalysisDetailsIntegrate ShareReportDialog with multi-analysis2h2.3.1High
2.3.4Create UserReportsDialogFor admin panel - manage reports per user3h2.2.4Medium

Files: client/src/components/ShareReportDialog.jsx (new), client/src/pages/AnalysisDetails.jsx, client/src/pages/MultiAnalysisDetails.jsx, client/src/components/UserReportsDialog.jsx (new)

Epic 2.4: Frontend - Report Viewer Experience

Task IDTaskDescriptionHoursDepsPriority
2.4.1Create MyReports pageList only reports user has access to4h2.2.4High
2.4.2Update AppLayout for report_viewerConditional nav - minimal sidebar for report viewers3h2.4.1High
2.4.3Hide edit actions for viewersRemove edit/delete buttons when user is report_viewer2h2.4.2High
2.4.4Update AuthContextHandle report_viewer role, expose in context2h2.1.4High

Files: client/src/pages/MyReports.jsx (new), client/src/components/layout/AppLayout.jsx, client/src/contexts/AuthContext.jsx

Epic 2.5: Testing & QA

Task IDTaskDescriptionHoursDepsPriority
2.5.1Backend API testingTest grant/revoke/list endpoints, access checks3h2.2.6High
2.5.2Frontend E2E testingTest share flow, report viewer login, access restrictions4h2.4.4High
2.5.3Security reviewVerify report_viewer can’t access unauthorized content2h2.5.2High

Demo Criteria: Admin creates report_viewer → shares MultiAnalysis → viewer logs in → sees only that report → can view source files → no edit buttons visible.


Stage 3: PDF Export

Goal: Generate professional PDF exports of reports.

Total Hours: 38-46h (including QA)

Epic 3.1: Infrastructure

Task IDTaskDescriptionHoursDepsPriority
3.1.1Evaluate PDF generation optionsTest WeasyPrint in Lambda, document decision2h-High
3.1.2Set up WeasyPrintAdd to requirements, configure Lambda layer or container3h3.1.1High
3.1.3Create templates directorySet up api/src/templates/pdf/ for Jinja2 templates1h3.1.2High

Files: api/requirements.txt, api/src/templates/pdf/ (new directory)

Epic 3.2: PDF Service

Task IDTaskDescriptionHoursDepsPriority
3.2.1Create base HTML templateJinja2 template with header, TOC, section structure4h3.1.3High
3.2.2Create PDF stylesCSS for professional formatting, page breaks, branding3h3.2.1High
3.2.3Build section renderersFunctions to convert themes, custom fields, etc. to HTML4h3.2.1High
3.2.4Create PDFExportServiceMain service class with export_analysis() and export_multi_analysis()4h3.2.3High
3.2.5Handle custom fields in PDFRender personas, custom sections appropriately3h3.2.4Medium

Files: api/src/services/pdf_export.py (new), api/src/templates/pdf/report.html (new), api/src/templates/pdf/styles.css (new)

Epic 3.3: Backend API

Task IDTaskDescriptionHoursDepsPriority
3.3.1Analysis export endpointGET /analyses/{id}/export?format=pdf3h3.2.4High
3.3.2Multi-analysis export endpointGET /analyze/multi/{id}/export?format=pdf3h3.2.4High

Files: api/src/routers/analyses.py

Epic 3.4: Frontend

Task IDTaskDescriptionHoursDepsPriority
3.4.1Add export button to AnalysisDetailsDownload button with loading state2h3.3.1High
3.4.2Add export button to MultiAnalysisDetailsDownload button with loading state2h3.3.2High
3.4.3Handle download responseBlob download, filename from header2h3.4.1High

Files: client/src/pages/AnalysisDetails.jsx, client/src/pages/MultiAnalysisDetails.jsx

Epic 3.5: Testing & QA

Task IDTaskDescriptionHoursDepsPriority
3.5.1PDF generation testingTest with various report types, verify formatting3h3.4.3High
3.5.2Custom fields in PDFVerify personas, custom sections render correctly2h3.5.1High
3.5.3Large report testingTest with reports containing many themes/findings2h3.5.1Medium

Demo Criteria: Open MultiAnalysis → click Export PDF → PDF downloads with header, TOC, all sections formatted professionally.


Stage 4: Projects Foundation

Goal: Introduce Projects as organizational layer.

Total Hours: 46-54h (including QA)

Epic 4.1: Data Model

Task IDTaskDescriptionHoursDepsPriority
4.1.1Design projects schemaTable with org_id, name, description, color, icon, is_default2h-High
4.1.2Create Project modelSQLAlchemy model with relationships2h4.1.1High
4.1.3Add project_id to filesAlter files table, add foreign key2h4.1.2High
4.1.4Add project_id to analysis_runsAlter analysis_runs table1h4.1.2High
4.1.5Add project_id to multi_analysesAlter multi_analyses table1h4.1.2High
4.1.6Add project_id to prompt_templatesOptional FK (NULL = org-wide)1h4.1.2High

Files: api/src/shared/db_models.py

Epic 4.2: Migration Strategy

Task IDTaskDescriptionHoursDepsPriority
4.2.1Write schema migrationAdd projects table and project_id columns (nullable first)3h4.1.6High
4.2.2Create default projectsData migration: create default project per org2h4.2.1High
4.2.3Migrate existing dataMove files/analyses to default project2h4.2.2High
4.2.4Make project_id requiredSecond migration to add NOT NULL constraint1h4.2.3High

Files: api/migrations/versions/xxx_add_projects.py, api/migrations/versions/xxx_migrate_to_projects.py

Epic 4.3: Backend API

Task IDTaskDescriptionHoursDepsPriority
4.3.1Create projects routerNew routers/projects.py with CRUD3h4.2.4High
4.3.2Projects list endpointGET /projects with file counts, last activity2h4.3.1High
4.3.3Project CRUD endpointsCreate, read, update, delete (protect default)3h4.3.1High
4.3.4Update files endpointsAdd project_id filter to list, require on create2h4.2.4High
4.3.5Update analyses endpointsAdd project_id filter and parameter2h4.2.4High
4.3.6Update prompts endpointsAdd project_id filter, include_org_wide param2h4.2.4High

Files: api/src/routers/projects.py (new), api/src/routers/files.py, api/src/routers/analyses.py, api/src/routers/prompts.py

Epic 4.4: Frontend

Task IDTaskDescriptionHoursDepsPriority
4.4.1Create ProjectContextContext provider with projects list, current project, persistence4h4.3.2High
4.4.2Update Sidebar with projectsProject list section with switcher, color indicators4h4.4.1High
4.4.3Create new project dialogForm for name, description, color, icon2h4.3.3High
4.4.4Update Files pageFilter by current project2h4.4.1High
4.4.5Update Upload pageInclude project_id in file creation1h4.4.1High
4.4.6Update MultiAnalysis pageInclude project_id1h4.4.1High
4.4.7Update PromptTemplates pageFilter by project, show org-wide toggle2h4.4.1Medium

Files: client/src/contexts/ProjectContext.jsx (new), client/src/components/layout/Sidebar.jsx, client/src/components/NewProjectDialog.jsx (new), client/src/pages/Files.jsx, client/src/pages/Upload.jsx, client/src/pages/MultiAnalysis.jsx, client/src/pages/PromptTemplates.jsx

Epic 4.5: Testing & QA

Task IDTaskDescriptionHoursDepsPriority
4.5.1Migration testingTest migration on copy of prod data, verify no data loss3h4.2.4High
4.5.2Project switching E2ETest create project, switch, verify isolation3h4.4.7High
4.5.3Backward compatibilityVerify existing workflows still work with default project2h4.5.2High

Demo Criteria: Login → see projects in sidebar → create “Q1 Interviews” → switch to it → upload file → switch back → file not visible → original files in Default Project.


Stage 5: Project RBAC

Goal: Control who can access which projects.

Total Hours: 40-48h (including QA)

Epic 5.1: Data Model

Task IDTaskDescriptionHoursDepsPriority
5.1.1Design project_memberships schemaTable with project_id, user_id, role (viewer/editor)2hStage 4High
5.1.2Create ProjectMembership modelSQLAlchemy model with relationships2h5.1.1High
5.1.3Write Alembic migrationCreate table, add existing users to default project2h5.1.2High

Files: api/src/shared/db_models.py, api/migrations/versions/xxx_add_project_memberships.py

Epic 5.2: Access Control Logic

Task IDTaskDescriptionHoursDepsPriority
5.2.1Create access control functionsget_project_access(), get_accessible_projects()3h5.1.3High
5.2.2Create access decoratorrequire_project_access(min_access) dependency3h5.2.1High
5.2.3Update projects listFilter to only accessible projects2h5.2.1High
5.2.4Update file/analysis queriesAdd project access checks3h5.2.2High

Files: api/src/deps.py, api/src/routers/projects.py, api/src/routers/files.py, api/src/routers/analyses.py

Epic 5.3: Backend API

Task IDTaskDescriptionHoursDepsPriority
5.3.1List members endpointGET /projects/{id}/members2h5.1.3High
5.3.2Add member endpointPOST /projects/{id}/members3h5.1.3High
5.3.3Update member role endpointPUT /projects/{id}/members/{user_id}2h5.1.3High
5.3.4Remove member endpointDELETE /projects/{id}/members/{user_id}2h5.1.3High

Files: api/src/routers/projects.py

Epic 5.4: Frontend

Task IDTaskDescriptionHoursDepsPriority
5.4.1Create ProjectMembersDialogDialog to view/manage project members4h5.3.1High
5.4.2Create AddMemberFormUser selector with role dropdown2h5.4.1High
5.4.3Add access indicator to sidebarEye icon for view-only projects2h5.2.3Medium
5.4.4Conditional edit actionsHide upload/edit/delete for viewers3h5.2.3High
5.4.5Update ProjectContextInclude user_role in project data2h5.2.3High

Files: client/src/components/ProjectMembersDialog.jsx (new), client/src/components/AddMemberForm.jsx (new), client/src/components/layout/Sidebar.jsx, client/src/pages/Files.jsx, client/src/contexts/ProjectContext.jsx

Epic 5.5: Testing & QA

Task IDTaskDescriptionHoursDepsPriority
5.5.1Access control testingTest viewer vs editor permissions3h5.4.5High
5.5.2Admin override testingVerify org admins have full access2h5.5.1High
5.5.3Security reviewTest unauthorized access attempts3h5.5.2High

Demo Criteria: Admin creates project → adds User A as Editor, User B as Viewer → User A can upload → User B sees eye icon, can’t upload → User C doesn’t see project at all.


Stage 6: File Organization

Goal: Folders and visibility controls for files.

Total Hours: 48-56h (including QA)

Epic 6.1: Data Model

Task IDTaskDescriptionHoursDepsPriority
6.1.1Design folders schemaTable with project_id, parent_folder_id, name, path_names2hStage 5High
6.1.2Create Folder modelSQLAlchemy model with self-referential relationship3h6.1.1High
6.1.3Add folder_id to filesFK to folders table1h6.1.2High
6.1.4Add visibility to filesEnum column: private/project/organization2h6.1.2High
6.1.5Write Alembic migrationCreate folders table, alter files2h6.1.4High

Files: api/src/shared/db_models.py, api/migrations/versions/xxx_add_folders_visibility.py

Epic 6.2: Visibility Logic

Task IDTaskDescriptionHoursDepsPriority
6.2.1Create visibility access functioncan_view_file() with visibility rules3h6.1.5High
6.2.2Create visibility query filterfilter_files_by_visibility() for list queries3h6.2.1High
6.2.3Update file access checksIntegrate visibility into existing access logic2h6.2.2High

Files: api/src/deps.py, api/src/routers/files.py

Epic 6.3: Backend API

Task IDTaskDescriptionHoursDepsPriority
6.3.1Create folders routerNew routers/folders.py2h6.1.5High
6.3.2Folders CRUD endpointsCreate, list (tree), update, delete4h6.3.1High
6.3.3Folder tree queryRecursive CTE for nested structure3h6.3.2High
6.3.4Update files endpointsAdd folder_id, visibility params2h6.1.5High
6.3.5Move file endpointUpdate file’s folder_id1h6.3.4Medium

Files: api/src/routers/folders.py (new), api/src/routers/files.py

Epic 6.4: Frontend

Task IDTaskDescriptionHoursDepsPriority
6.4.1Create FolderTree componentCollapsible tree view with selection5h6.3.3High
6.4.2Create FolderSelector dropdownFor upload page folder selection2h6.4.1High
6.4.3Create VisibilitySelectorDropdown with private/project/org options2h-High
6.4.4Create Breadcrumbs componentShow current folder path2h6.4.1Medium
6.4.5Update Files page layoutAdd folder sidebar, breadcrumbs4h6.4.1, 6.4.4High
6.4.6Update Upload pageAdd folder and visibility selectors2h6.4.2, 6.4.3High
6.4.7Add visibility indicator to FileRowIcons for private/project/org1h6.4.3Medium
6.4.8Create new folder dialogForm for folder name, color2h6.3.2High

Files: client/src/components/FolderTree.jsx (new), client/src/components/FolderSelector.jsx (new), client/src/components/VisibilitySelector.jsx (new), client/src/components/Breadcrumbs.jsx (new), client/src/pages/Files.jsx, client/src/pages/Upload.jsx, client/src/components/files/FileRow.jsx

Epic 6.5: Testing & QA

Task IDTaskDescriptionHoursDepsPriority
6.5.1Folder operations testingCreate, nest, move, delete folders3h6.4.8High
6.5.2Visibility testingTest private/project/org access rules3h6.4.7High
6.5.3Cross-user visibilityVerify correct files visible per user/project3h6.5.2High
6.5.4Edge casesEmpty folders, deep nesting, orphaned files2h6.5.3Medium

Demo Criteria: Create folder “Week 1” → create subfolder “Day 1” → upload file to Day 1 as “Project” visibility → change to “Private” → other user can’t see it → change to “Organization” → users outside project can see it.


Summary

StageTasksHoursPriority
Stage 0: Report Fixes1122-26hP0
Stage 1: Attachments1434-40hP1
Stage 2: Report Sharing1842-50hP1
Stage 3: PDF Export1438-46hP1
Stage 4: Projects2046-54hP1
Stage 5: Project RBAC1640-48hP2
Stage 6: File Organization2148-56hP2
Total114270-320h

Milestones

MilestoneAfter StageDemonstrates
DEMO 10, 1, 2Report fixes working, attachments in LLM, sharing functional
DEMO 23, 4PDF export, projects foundation
DEMO 35, 6Full RBAC, file organization complete